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

Reset the database and start fresh:

keel run --reset

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

Examples

Run all tests:

keel test

Run only tests matching a pattern:

keel test --pattern "createOrder"

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 seed

Apply seed data to your local database.

keel seed

This command executes SQL files in your project's seed/ directory to populate your database with initial data.

Snapshot

Create a database snapshot after seeding:

keel seed snapshot

This is useful for creating a known database state that you can restore to later.

Seed directory structure

Create a seed/ directory in your project root with SQL files:

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

Files are executed in alphabetical order, so prefix them with numbers to control the order.

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.