@contract-kit/cli

Command-line interface for scaffolding and managing Contract Kit applications. Streamlines the creation of contracts, use cases, routes, and providers with intelligent code generation.

Installation

Global Installation (Recommended)

npm install -g @contract-kit/cli

Per-Project Installation

npm install --save-dev @contract-kit/cli

TypeScript Requirements

This package requires TypeScript 5.0 or higher.

Quick Start

Create a New Application

contract-kit new my-app
cd my-app
bun run dev

Add to Existing Next.js App

cd my-existing-app
contract-kit init

Commands

contract-kit new <app-name>

Scaffold a new Contract Kit application with Next.js.

Options:

• -t, --template <template>: Template to use (default: hex-minimal)
  • hex-minimal: Minimal setup with core packages
  • hex-fullstack: Full-featured setup with database, auth, and more
• -p, --package-manager <pm>: Package manager (bun, pnpm, npm, yarn)
• --no-install: Skip dependency installation
• --no-git: Skip git initialization

Examples:

# Create with default template
contract-kit new my-app

# Create with fullstack template
contract-kit new my-app --template hex-fullstack

# Create with specific package manager
contract-kit new my-app --package-manager pnpm

# Create without installing dependencies
contract-kit new my-app --no-install

contract-kit init

Set up Contract Kit in an existing Next.js application.

Options:

• --app-root <path>: Relative path to app root (default: auto-detect)

Examples:

# Auto-detect app structure
contract-kit init

# Specify app root
contract-kit init --app-root src/app

This command will:

• Install required dependencies
• Create folder structure (contracts, use-cases, etc.)
• Add example contract and use case
• Configure TypeScript paths
• Create server configuration

contract-kit generate (alias: g)

Generate code for contracts, use cases, routes, jobs, and providers.

Generate Contract

contract-kit generate contract <name>
contract-kit g contract <name>  # shorthand

Options:

• -m, --method <method>: HTTP method (GET, POST, PUT, PATCH, DELETE) - default: GET
• -p, --path <path>: API path (e.g., /api/todos)
• -g, --group <group>: Group name for organizing contracts
• --dry-run: Preview changes without writing files

Examples:

# Generate a GET contract
contract-kit g contract todos.list --method GET --path /api/todos

# Generate a POST contract
contract-kit g contract todos.create --method POST --path /api/todos

# Generate with grouping
contract-kit g contract users.list --method GET --path /api/users --group users

# Preview without creating files
contract-kit g contract todos.get --dry-run

Generated files:

• contracts/<group>/<name>.ts: Contract definition
• Includes proper TypeScript types and Zod schemas

Generate Use Case

contract-kit generate usecase <name>
contract-kit g usecase <name>  # shorthand

Options:

• -t, --type <type>: Use case type (query, command) - default: query
• -c, --contract <contract>: Link to a contract
• --dry-run: Preview changes without writing files

Examples:

# Generate a query use case
contract-kit g usecase todos.list --type query

# Generate a command use case
contract-kit g usecase todos.create --type command

# Link to a contract
contract-kit g usecase todos.list --contract todos.list

# Preview without creating files
contract-kit g usecase users.get --dry-run

Generated files:

• use-cases/<group>/<name>.ts: Use case implementation
• use-cases/<group>/<name>.test.ts: Test file
• Includes proper ports/dependencies injection

Generate Route

contract-kit generate route <contract-name>
contract-kit g route <contract-name>  # shorthand

Options:

• -m, --method <method>: HTTP method (GET, POST, PUT, PATCH, DELETE)
• -u, --usecase <usecase>: Link to a use case
• --catch-all: Generate for catch-all routing
• --dry-run: Preview changes without writing files

Examples:

# Generate route for a contract
contract-kit g route todos.list --method GET

# Generate route with use case
contract-kit g route todos.create --method POST --usecase todos.create

# Generate for catch-all routing
contract-kit g route todos.list --catch-all

# Preview without creating files
contract-kit g route todos.get --dry-run

Generated files:

• app/api/<path>/route.ts: Next.js route handler
• Properly wired to contract and optionally use case

Generate Job

contract-kit generate job <name>
contract-kit g job <name>  # shorthand

Options:

• --schedule <cron>: Cron schedule for recurring job
• --dry-run: Preview changes without writing files

Examples:

# Generate a job
contract-kit g job send-welcome-email

# Generate scheduled job
contract-kit g job cleanup-old-data --schedule "0 0 * * *"

# Preview without creating files
contract-kit g job process-queue --dry-run

Generated files:

• jobs/<name>.ts: Job definition with Inngest integration
• jobs/index.ts: Updated job registry

Generate Provider

contract-kit generate provider <name>
contract-kit g provider <name>  # shorthand

Options:

• -t, --type <type>: Provider type (db, cache, logger, mail, etc.)
• --dry-run: Preview changes without writing files

Examples:

# Generate a provider
contract-kit g provider my-service --type db

# Preview without creating files
contract-kit g provider custom-logger --type logger --dry-run

Generated files:

• providers/<name>.ts: Custom provider implementation
• Includes port implementation scaffold

contract-kit dev

Start development server with enhanced tooling.

contract-kit dev

Features:

• Runs Next.js dev server
• Watches for contract changes
• Auto-generates TypeScript types
• Provides development-time validation

contract-kit openapi

Generate OpenAPI/Swagger documentation from your contracts.

Options:

• -o, --output <file>: Output file path (default: openapi.json)
• -t, --title <title>: API title
• -v, --version <version>: API version
• --yaml: Output as YAML instead of JSON
• --serve: Start a documentation server

Examples:

# Generate openapi.json
contract-kit openapi

# Generate with custom output
contract-kit openapi --output docs/api-spec.json

# Generate with metadata
contract-kit openapi --title "My API" --version "1.0.0"

# Generate as YAML
contract-kit openapi --output api-spec.yaml --yaml

# Generate and serve documentation
contract-kit openapi --serve

Project Structure

When you run contract-kit init or contract-kit new, the CLI creates this structure:

my-app/
├── app/
│   ├── api/
│   │   └── [...contract-kit]/
│   │       └── route.ts          # Catch-all API handler
│   └── lib/
│       └── server.ts              # Server configuration
├── contracts/
│   └── todos/
│       ├── list.ts
│       └── create.ts
├── use-cases/
│   └── todos/
│       ├── list.ts
│       ├── list.test.ts
│       ├── create.ts
│       └── create.test.ts
├── providers/
│   └── index.ts
├── jobs/
│   └── index.ts
└── tsconfig.json

Configuration

The CLI reads configuration from contract-kit.config.js or contract-kit.config.ts:

// contract-kit.config.ts
export default {
  // Path to app directory
  appRoot: "app",

  // Path to contracts directory
  contractsDir: "contracts",

  // Path to use cases directory
  useCasesDir: "use-cases",

  // Path to providers directory
  providersDir: "providers",

  // Path to jobs directory
  jobsDir: "jobs",

  // Template settings
  templates: {
    // Use custom templates
    contract: "./templates/contract.ejs",
    useCase: "./templates/usecase.ejs",
  },

  // OpenAPI settings
  openapi: {
    title: "My API",
    version: "1.0.0",
    description: "API documentation",
  },
};

Templates

The CLI uses built-in templates for code generation. You can override them by:

1. Create a .contract-kit/templates directory in your project
2. Add template files (contract.ejs, usecase.ejs, etc.)
3. CLI will use your templates instead of built-in ones

Available Template Variables

Contract Template:

• name: Contract name
• method: HTTP method
• path: API path
• group: Contract group

Use Case Template:

• name: Use case name
• type: Use case type (query/command)
• contractName: Linked contract (if any)
• group: Use case group

Route Template:

• contractName: Contract name
• method: HTTP method
• useCaseName: Linked use case (if any)
• catchAll: Is catch-all route

Environment Setup

The CLI respects your environment configuration:

# .env.local
DATABASE_URL=...
REDIS_URL=...
INNGEST_EVENT_KEY=...

These are automatically loaded in generated code.

Migration from Other Frameworks

From tRPC

# Install CLI
npm install @contract-kit/cli

# Initialize in existing project
contract-kit init

# Generate contracts from tRPC routers
# (manual migration, but structure is similar)

From Next.js API Routes

# Initialize Contract Kit
contract-kit init

# Generate contracts for existing routes
contract-kit g contract users.list --method GET --path /api/users
contract-kit g contract users.get --method GET --path /api/users/:id

Troubleshooting

Command not found

If you get "command not found" after global installation:

# Check if npm bin is in PATH
echo $PATH

# Add to PATH if needed (add to ~/.zshrc or ~/.bashrc)
export PATH="$PATH:$(npm bin -g)"

TypeScript errors after generation

# Restart TypeScript server in your editor
# Or rebuild the project
bun run build

Module resolution errors

Ensure your tsconfig.json has proper paths configuration:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Examples

Create Todo App

# Create new app
contract-kit new todo-app

# Generate contracts
cd todo-app
contract-kit g contract todos.list --method GET --path /api/todos
contract-kit g contract todos.create --method POST --path /api/todos
contract-kit g contract todos.update --method PUT --path /api/todos/:id
contract-kit g contract todos.delete --method DELETE --path /api/todos/:id

# Generate use cases
contract-kit g usecase todos.list --type query
contract-kit g usecase todos.create --type command
contract-kit g usecase todos.update --type command
contract-kit g usecase todos.delete --type command

# Generate routes (if not using catch-all)
contract-kit g route todos.list --usecase todos.list
contract-kit g route todos.create --usecase todos.create

# Start development
bun run dev

Add Auth to Existing App

# Generate auth contract
contract-kit g contract auth.login --method POST --path /api/auth/login
contract-kit g contract auth.logout --method POST --path /api/auth/logout
contract-kit g contract auth.me --method GET --path /api/auth/me

# Generate auth use cases
contract-kit g usecase auth.login --type command
contract-kit g usecase auth.logout --type command
contract-kit g usecase auth.getCurrentUser --type query

# Generate routes
contract-kit g route auth.login --usecase auth.login
contract-kit g route auth.logout --usecase auth.logout
contract-kit g route auth.me --usecase auth.getCurrentUser

Related Packages

• @contract-kit/core - Contract definitions
• @contract-kit/server - Server runtime
• @contract-kit/next - Next.js adapter
• @contract-kit/openapi - OpenAPI generation

Contributing

Issues and pull requests welcome at https://github.com/taylorbryant/contract-kit

License

MIT