@codapult/cli

CLI tool for managing Codapult SaaS projects, including architecture-control workflows powered by @codapult/guard.

@codapult/cli is the open-source developer CLI and MCP server for Codapult-based SaaS projects. It provides project setup, updates, plugins, database, deployment, MCP, and architecture-control workflows.

For a non-Codapult JavaScript or TypeScript project, install @codapult/guard directly. The CLI does not make Guard universal by adding Codapult assumptions to it; within Codapult projects, the CLI includes the same published Guard package through a thin adapter.

| Package | Use it when | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | @codapult/guard | You need architecture guardrails, project memory, MCP, and AI-agent verification in any JS/TS project. | | @codapult/cli | You are building a Codapult SaaS and also need setup, plugins, database, environment, and deployment workflows. |

Installation

This is the maintained CLI package used by Codapult projects. Buyers normally invoke the published package through npx or the generated MCP configuration; they do not clone or build this repository. The CLI also powers Codapult MCP, exposing project-aware tools, resources, and prompt templates to compatible AI coding clients. The development and release sections below are for Codapult maintainers.

npm install -g @codapult/cli

Or run directly with npx:

npx @codapult/cli <command>

The command reference below uses the installed codapult binary. For reproducible project and CI usage, install and pin it as a dev dependency:

pnpm add -D @codapult/cli

Project users who do not install the CLI globally should prefix commands with npx @codapult/cli, for example npx @codapult/cli db schema-diff.

Verified project workflow

The CLI repository includes an executable golden-path contract for the workflow used by a new Codapult project:

create → setup → run → MCP status/generate → project checks → Guard → test

Maintainers can run it with:

pnpm test:golden

The check creates a temporary shallow-clone source, starts the generated project locally, verifies its health endpoint, connects to MCP, generates a page, runs the project test through MCP, and finishes with Guard initialization, proposal, and verification. It uses no external provider credentials. Authentication and payment-provider flows remain covered by their focused adapter, route, webhook, and application E2E tests.

Commands

Project

• codapult setup — interactive project setup wizard (or non-interactive with --preset)
• codapult recipe list|show|apply <name> — inspect or apply a starter workflow
• codapult update [version] — update from upstream Codapult releases
• codapult doctor — check project health and configuration (exit code 1 on failures for CI)
• codapult config — show current project configuration

Plugins

• codapult plugins add <name> — install a plugin from a local directory or remote Git URL
• codapult plugins remove <name> — uninstall a plugin
• codapult plugins migrate [name] — update plugin schema and generate DB migration (--push for dev mode)
• codapult plugins list — list installed plugins
• codapult plugins check [name] — verify plugin install compatibility without changing files

Code Generation

• codapult generate page <name> — create a dashboard page
• codapult generate api <name> — create an API route (auth + rate limit + Zod)
• codapult generate action <name> — create a server action
• codapult generate plugin <name> — scaffold a new plugin repository

Database

• codapult db push — apply schema to database
• codapult db generate — generate migration files
• codapult db seed — seed sample data
• codapult db studio — open Drizzle Studio
• codapult db status — show schema info and migration count
• codapult db schema-diff — compare SQLite and PostgreSQL schema files
• codapult db live-diff — read-only compare active schema with the live database

Environment

• codapult env check — validate .env.local against .env.example
• codapult env sync — add missing variables from .env.example

Deployment

• codapult deploy vercel — build and deploy to Vercel
• codapult deploy docker — build Docker image
• codapult deploy status — check deploy readiness

Architecture Guard

Codapult CLI includes the @codapult/guard engine and keeps the codapult guard ... command surface as a Codapult-friendly entrypoint. Guard is responsible for project architecture memory, approved contracts, baselines, changed-file regressions, impact context, and AI-agent review packets. It does not replace ESLint, TypeScript, tests, SAST, or a general PR-review service.

• codapult guard init — discover the project and create .codapult/guard/ state and baseline
• codapult guard analyze — refresh project facts without changing the baseline
• codapult guard propose — generate evidence-based rules and contract proposals
• codapult guard check --changed — check new architecture violations
• codapult guard audit — inspect the complete current state, including baseline findings
• codapult guard review — prepare a bounded diff and project-context packet for an AI reviewer
• codapult guard impact <files...> — explain dependencies, transitive dependents, capabilities, and relevant contracts
• codapult guard verify — run Guard verification and configured project checks
• codapult guard doctor — diagnose missing or invalid Guard artifacts
• codapult guard rules ... — approve proposed rules
• codapult guard contracts ... — approve or reject proposed contracts
• codapult guard baseline ... — inspect or intentionally update accepted findings

For any JavaScript or TypeScript project, install the standalone package directly:

pnpm add -D @codapult/guard
pnpm exec codapult-guard init

The Codapult CLI adapter and the standalone Guard package share the same implementation; Guard logic is not duplicated in this repository. This section documents only the Codapult-specific entrypoints. The standalone Guard README and Guard documentation are the source of truth for the complete lifecycle, contracts, impact analysis, AI-agent workflow, MCP tools, CI, and current Guard capabilities.

AI Integration

• codapult mcp update [version] — pin or update the MCP version in .cursor/mcp.json
• codapult mcp doctor — run shared project health checks plus validate .cursor/mcp.json
• codapult mcp contract-check — fail CI when env-schema.ts drifts from the MCP compatibility contract
• codapult mcp-server — start MCP server for AI assistant integration (Cursor, Claude, Codex)

Global options available on every command include --help and --version. Commands that read project configuration accept --no-env-file where applicable. Use --dry-run on commands that document it to preview a change without applying it.

Mutation commands (db push, db generate, plugins add/remove, env sync, and code generation) can change project files or databases. Use their dry-run options where available, review the returned plan, and keep them behind an explicit developer/CI step. Diagnostic commands (doctor, env check, deploy status, mcp contract-check, db schema-diff, and db live-diff) are read-only and return non-zero exit codes on failures, except type-only schema parity warnings.

MCP Server

The CLI includes an MCP (Model Context Protocol) server for working with Codapult projects. Its core integration exposes 29 tools, 8 resources, and 2 prompt templates. The integrated Guard capabilities add 14 tools, 6 resources, and 2 prompt templates. The resulting current full surface is 43 tools, 14 resources, and 4 prompt templates.

MCP Tools

The tools below are the Codapult template integration. Guard tools are documented in the @codapult/guard repository and are registered by the CLI as its architecture-control layer.

Project

| Tool | Description | | -------------------------- | ------------------------------------------------------------------------------- | | codapult_project_status | Report adapters, plugins, enabled features, and git status. | | codapult_project_config | Read the application configuration from src/config/app.ts. | | codapult_project_context | Return a compact project overview for AI-assisted work. | | codapult_run_checks | Run lint, typecheck, and/or tests. | | codapult_build | Run the production build. | | codapult_doctor | Check project files, TypeScript, environment, schema parity, and configuration. |

Database

| Tool | Description | | ---------------------------- | ------------------------------------------------------------------------ | | codapult_db_get_tables | List database tables with column counts. | | codapult_db_get_table_info | Inspect columns, types, and constraints for a table. | | codapult_db_status | Report the database provider, table count, and migration status. | | codapult_db_schema_diff | Compare the SQLite and PostgreSQL host schema files. | | codapult_db_migration_diff | Preview pending SQL in a temporary migration directory. | | codapult_db_live_diff | Read-only comparison of the active source schema with the live database. | | codapult_db_generate | Generate a Drizzle migration. | | codapult_db_push | Apply the source schema to the database. | | codapult_db_seed | Run the project's database seed script. |

Environment

| Tool | Description | | --------------------- | ------------------------------------------------------------------------------------ | | codapult_env_schema | Read documented variables and descriptions from .env.example. | | codapult_env_read | Read and validate local environment values with secrets masked by default. | | codapult_env_update | Set one environment variable in the project env file. | | codapult_env_check | Validate local variables against .env.example and effective provider requirements. | | codapult_env_sync | Add missing variables from .env.example to the local env file. |

Plugins

| Tool | Description | | -------------------------- | -------------------------------------------------------------- | | codapult_plugins_list | List installed plugins. | | codapult_plugins_add | Install a plugin and patch its config and schema declarations. | | codapult_plugins_remove | Uninstall a plugin. | | codapult_plugins_migrate | Update a plugin schema and prepare a database migration. |

Code Generation

| Tool | Description | | -------------------------- | ------------------------------------------------------------------- | | codapult_generate_page | Generate a dashboard page with the project conventions. | | codapult_generate_api | Generate an API route with auth, rate limiting, and Zod validation. | | codapult_generate_action | Generate a server action with auth and validation. | | codapult_generate_plugin | Scaffold a complete plugin repository. |

Deployment

| Tool | Description | | ------------------------ | --------------------------------------------------------------- | | codapult_deploy_status | Check Docker, Helm, Terraform, and Pulumi deployment readiness. |

Architecture Guard

| Tool | Description | | -------------------------------- | ---------------------------------------------------------------------------------------------------- | | codapult_guard_init | Discover the project and create Guard state and an initial baseline. | | codapult_guard_context | Return project architecture context for an AI agent. | | codapult_guard_propose | Generate evidence-based rule and contract proposals. | | codapult_guard_proposal_decide | Approve or reject proposed Guard policy. | | codapult_guard_check | Check active Guard policy against the project or changed files. | | codapult_guard_audit | Run a complete Guard scan, including baseline-suppressed findings. | | codapult_guard_review | Prepare a bounded semantic-review packet from the current diff. | | codapult_guard_verify | Run Guard, project checks, adapters, and contract verification. | | codapult_guard_impact | Analyze dependencies, transitive dependents, capabilities, contracts, and architecture impact paths. | | codapult_guard_explain | Explain Guard findings and project-specific architectural constraints. |

Mutating MCP tools support dry_run where applicable. The tool returns the planned operations without writing project files, changing environment files, running migrations, or applying database changes. codapult_env_read masks sensitive values by default; show_secrets: true is optional and returns a security warning.

MCP Resources

Resources are read-only project files or computed context that MCP clients can load automatically.

| Resource | URI | Description | | ----------------------- | ------------------------------ | --------------------------------------------------------------------------------- | | codapult_schema | codapult://schema | Active Drizzle schema selected by the database provider. | | codapult_app_config | codapult://config/app | Application identity, brand, and company configuration. | | codapult_env_config | codapult://config/env | Typed environment access, AI feature flags, providers, and checkout resolution. | | codapult_agents_md | codapult://agents | Project structure, conventions, and AI-agent rules from AGENTS.md. | | codapult_env_example | codapult://env-example | Environment variable template with descriptions and defaults. | | codapult_validation | codapult://validation | Project Zod validation schemas. | | codapult_navigation | codapult://config/navigation | Dashboard and admin navigation configuration. | | codapult_config_files | codapult://config/files | All non-test TypeScript files in src/config, including marketing configuration. |

MCP Prompt Templates

| Prompt | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | | codapult_code_review | Review code against Codapult API, adapter, TypeScript, React, security, and database conventions; includes current project context. | | codapult_schema_design | Design matching SQLite and PostgreSQL Drizzle tables using the project's naming, key, timestamp, and relation conventions. |

codapult doctor and MCP use the same health/report core. The regular command is project-focused; codapult mcp doctor additionally verifies that the editor configuration points to the Codapult MCP server. Doctor also checks parity between src/lib/db/schema.ts and src/lib/db/schema-pg.ts; missing tables/columns fail the check and incompatible provider types are warnings. Environment schema drift is detected by parsing src/config/env-schema.ts with the TypeScript AST.

The environment, deployment-readiness, doctor, and MCP contract commands expose structured checks internally and render them for the terminal. MCP clients receive the same data as JSON. This keeps CI exit codes and interactive output aligned.

Database live-diff checks only the active schema of the project: src/lib/db/schema.ts for Turso/SQLite or src/lib/db/schema-pg.ts for PostgreSQL. plugins add and plugins migrate keep both schema files in sync with the plugin manifest when PostgreSQL tables are provided. A live table that is absent from the active host schema is reported as missing_in_schema; review it as a legacy table or install/integrate the plugin before changing the database. The checker does not scan sibling plugin repositories or plugin source files.

Development

pnpm install
pnpm dev          # watch mode — rebuild on changes
pnpm test         # run unit tests
pnpm lint         # lint
pnpm typecheck    # type-check without emitting

See CONTRIBUTING.md for the public repository workflow and SECURITY.md for vulnerability reporting and safe CLI usage.

Releasing

Releases are managed with release-it. The workflow:

1. Run the release command on the main branch:

pnpm run release          # interactive — prompts for version bump type
pnpm run release -- patch # non-interactive patch bump (0.18.1 → 0.18.2)
pnpm run release -- minor # minor bump (0.18.1 → 0.19.0)
pnpm run release -- major # major bump (0.18.1 → 1.0.0)

2. release-it will automatically:

   • Run pre-release checks (lint, typecheck, test)
   • Bump the version in package.json
   • Update CHANGELOG.md from Conventional Commits
   • Commit the changes (chore: release v<version>)
   • Create a Git tag (v<version>)
   • Push the commit and tag to origin
   • Create a published GitHub Release for the tag

3. The published GitHub Release triggers .github/workflows/release.yml, which checks out the exact tag, validates the package, and publishes it to npm. GitHub Release is the reviewed release record; npm remains the distribution channel.

Dry run

Preview what a release would do without making any changes:

pnpm run release -- --dry-run

Prerequisites

• npm trusted publishing must be configured for the @codapult/cli package on npmjs.com.
• The npm trusted publisher must point to this repository's .github/workflows/release.yml workflow and allow direct npm publish.
• Before publishing a CLI release, the standalone codapult-guard package must be available on npm and the CLI dependency must use its published version rather than the pre-release workspace file: dependency.
• Commit messages should follow Conventional Commits for meaningful changelogs (e.g. feat:, fix:, chore:).

License

MIT