CLI

The Keel CLI is your primary tool for developing, testing, and deploying Keel applications. It handles everything from project initialization to local development, testing, and self-hosted deployments.

Installing Keel CLI

The Keel CLI can be installed from NPM:

npm install -g keel

To verify the installation and check your version:

keel --version

Global flags

These flags are available on all commands:

Commands overview

keel init

Initialize a new Keel project with an interactive setup wizard.

keel init

The init command guides you through:

1. Directory — Choose where to create your project
2. Template — Start with a blank project or a starter template
3. Package Manager — Select npm or pnpm
4. Version Control — Optionally initialize a Git repository

What gets created

For a blank project, keel init creates:

my-keel-app/
├── schema.keel        # Your Keel schema
├── keelconfig.yaml    # Project configuration
├── .gitignore         # Git ignore rules
├── package.json       # Node.js dependencies
└── node_modules/      # Installed packages

The command also runs keel generate automatically to create the @teamkeel/sdk and @teamkeel/testing packages.

Starter templates

When you select "Starter template", the CLI downloads templates from the teamkeel/starter-templates (opens in a new tab) repository and lets you choose from available options.

keel run

Start a local development server for your Keel project.

keel run

This command:

• Sets up a local PostgreSQL database using Docker
• Runs any pending database migrations
• Validates your schema
• Sets up your functions
• Starts a development server on port 8000
• Watches for changes to your schema and function files

Flags

Examples

Run on a different port:

keel run --port 3000

When keel run creates a fresh, empty database, it seeds it automatically after applying migrations. To skip that, use --no-seed:

keel run --no-seed

To start from a clean database, reset it first with keel db reset, then run:

keel db reset
keel run

Use an external PostgreSQL database instead of Docker:

keel run --database-url postgresql://user:password@localhost:5432/mydb

This is useful if you prefer to manage your own PostgreSQL instance during local development or need to connect to a specific database setup.

GraphiQL playground

While the development server is running, you can access a GraphiQL playground at:

http://localhost:8000/api/graphiql

This provides an interactive environment to explore and test your GraphQL API.

keel generate

Generate the @teamkeel/sdk package and scaffold missing function files.

keel generate

This command:

• Generates @teamkeel/sdk with TypeScript types from your schema
• Generates @teamkeel/testing for writing tests
• Creates stub files for any custom functions defined in your schema

keel validate

Validate your Keel schema and configuration files.

keel validate

If your project is valid, you'll see:

✨ Everything's looking good!

If there are errors, they're displayed with context showing exactly where the problem is in your schema or config files.

Flags

JSON output

For integration with editors and CI pipelines, use --json to get structured output:

keel validate --json

This returns a JSON object with validationErrors and configErrors arrays.

keel test

Run your test suite using Vitest (opens in a new tab).

keel test

Keel's test runner:

• Starts a sandboxed database for test isolation
• Builds your project and starts a test server
• Runs Vitest with your test files
• Cleans up resources after tests complete

Flags

With --parallel N, Keel runs your test files across N isolated stacks, each with its own database and functions server. Files are shared across up to 8 runners and balanced by how long they took on the previous run. The default is --parallel 1, which runs serially. Pressing Ctrl-C cancels a run cleanly.

Examples

Run all tests:

keel test

Run only tests matching a pattern:

keel test --pattern "createOrder"

Run test files in parallel across 4 stacks:

keel test --parallel 4

keel client

Generate a TypeScript client SDK for your Keel API.

keel client

This creates a fully-typed TypeScript client that you can use in frontend applications, scripts, or other services to interact with your Keel API.

Flags

Examples

Generate a client for your default API:

keel client

Generate a client for a specific API into a lib directory:

keel client --api web --output ./lib

Generate as a standalone package:

keel client --package --output ./packages/api-client

Watch mode for development:

keel client --watch --output ./src/lib

Single file vs package

By default, keel client generates a single TypeScript file. This works well for most use cases.

With --package, it generates a complete npm package structure with its own package.json. This is useful when you want to:

• Share the client across multiple projects
• Publish the client to a private npm registry
• Keep the client in a monorepo package

keel db

Manage your local development database. These subcommands connect to a running database.

See Seeding data for the full seeding workflow.

keel db seed

Apply the SQL files in your project's seed/ directory to the development database.

keel db seed

Seeding is non-destructive by default: existing rows are left untouched, so the command is safe to run again.

Files run in alphabetical order, so prefix them with numbers to control the order:

my-keel-app/
├── seed/
│   ├── 001_categories.sql
│   ├── 002_products.sql
│   └── 003_users.sql
├── schema.keel
└── keelconfig.yaml

keel db snapshot

Capture the current state of the database into a reusable seed file.

keel db snapshot

This writes to seed/snapshot/snapshot.sql. It is a read-only capture: it does not reset or re-seed the database. Pass a name to capture into a named scenario:

keel db snapshot demo

That writes to seed/demo/snapshot.sql, which you can recreate later with keel db seed --scenario demo.

keel db reset

Drop and recreate your development database, leaving it empty.

keel db reset

The next keel run re-applies your migrations from scratch and seeds the fresh database.

keel seed

Author seed data offline. These subcommands do not need a running database. To apply seed data to a database, use keel db seed.

keel seed

keel secrets

Manage secrets for local development and testing.

keel secrets

Secrets are stored in your CLI config at ~/.keel/config.yaml and are available to your Keel app during local development.

Subcommands

secrets list

List all secrets for an environment:

keel secrets list
keel secrets list --env test

secrets set

Set a secret value:

keel secrets set MY_API_KEY "sk-secret-value"
keel secrets set STRIPE_KEY "sk_test_..." --env test

secrets remove

Remove a secret:

keel secrets remove MY_API_KEY
keel secrets remove STRIPE_KEY --env test

Flags

Troubleshooting

Docker not running

If you see errors about Docker, ensure Docker Desktop is running:

docker ps

Port already in use

If port 8000 is already in use, specify a different port:

keel run --port 3001

Package manager issues

The CLI auto-detects your package manager from lockfiles. If you're having issues, ensure you have either package-lock.json (npm) or pnpm-lock.yaml (pnpm) in your project or a parent directory.