Quick Start

Prerequisites

• Node.js 22.18.0 or later
• pnpm — install via corepack enable && corepack prepare pnpm@latest --activate
• Git with access to the private Codapult repository (SSH or a configured Git credential helper)
• A database — local SQLite (file:local.db) is enough for development; use PostgreSQL or Turso for hosted environments
• Access to the private Codapult template repository through your GitHub account

Installation

npx @codapult/create my-app
cd my-app

This shallow-clones the template without its history, runs the setup wizard, and installs dependencies. You do not need to run the setup wizard again. If you cloned the template manually, run npx @codapult/cli setup before writing custom code.

For a named starting point, see Starter Profiles and Recipes.

Configuration

Copy the example environment file and fill in the required values:

cp .env.example .env.local

At minimum, set these variables for the default adapters:

TURSO_AUTH_TOKEN is also required when using Turso cloud (not needed for file:local.db). All other variables are optional and documented in .env.example.

Tip: To skip auth and payments setup, set APP_MODE="landing" — only TURSO_DATABASE_URL is required. This runs Codapult in marketing-only mode.

If you prefer PostgreSQL

Turso is the default because local setup is fast and a SQLite file works without external services. If your team prefers PostgreSQL, switch the database provider in .env.local:

DB_PROVIDER="postgres"
DATABASE_URL="postgresql://user:password@host:5432/dbname?sslmode=require"

When DB_PROVIDER=postgres, pnpm db:* commands use the PostgreSQL Drizzle schema and connection string automatically. Keep TURSO_DATABASE_URL only if you plan to switch back to the default Turso/LibSQL provider.

Database Setup

Push the schema to your configured database — this creates all tables in one step:

pnpm db:push

Optionally seed sample data (users, organizations, plans) for local testing:

pnpm db:seed

Start the Dev Server

pnpm dev

Open http://localhost:3000. You should see the Codapult landing page. Click Sign Up to create your first account.

Interactive Setup Wizard

When using @codapult/create, this wizard already ran during project creation. Run it manually only for a project cloned or downloaded without the creator:

npx @codapult/cli setup

The wizard walks you through the supported removal groups (authentication, AI surfaces, blog, teams, GraphQL, API docs, and other listed project capabilities) and removes the groups you do not need. It does not expose every capability as a separate prompt.

Review the generated change: The setup wizard updates the codebase by deleting files and routes mapped to disabled module groups and applying supported prune markers. Review shared schema, imports, and dependencies before generating migrations or writing custom code. This gives you a focused source tree for the product you are building.

Connect an AI coding agent

The CLI provides project setup, generators, health checks, and the Codapult MCP integration:

npx @codapult/cli doctor
npx @codapult/cli mcp doctor

Configure the generated .cursor/mcp.json in your editor, then ask the agent to inspect the project before changing it. For example:

Use Codapult MCP to inspect the current organization, database, and dashboard conventions.
Generate a protected dashboard page for saved reports and run the project checks.

Add architecture control with Guard

Guard adds architecture discovery and change verification to the Codapult workflow. It discovers the architecture that already exists and verifies changes against explicitly approved rules; it does not replace TypeScript, lint, or tests.

npx @codapult/cli guard init
npx @codapult/cli guard propose
npx @codapult/cli guard verify --json

Keep Guard state and policy review in the project repository. See the Guard documentation for the proposal, review, waiver, and CI lifecycle.

Useful Commands

Next Steps

• Project Structure — understand the directory layout and config files
• Authentication — configure sign-in methods, 2FA, and SSO
• Payments & Billing — set up subscription tiers and billing
• Customization — theming, branding, and white-label options