---
title: CLI reference
description: Generated command, argument, flag, and example reference for relkit 0.9.2.
search:
  exclude: true
sidebar:
  icon: terminal
---

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For guided setup and everyday workflows, start with the [CLI module](/docs/modules/cli) or follow [Create and build an API](/guides/cli/create-and-build-an-api). This page lists exact command arguments and options.

The command model below is shared with the Effect CLI runtime, so nested help and this page cannot drift.

## `relkit <command>`

Convention-first TypeScript application framework

| Option | Value   | Description                  |
| ------ | ------- | ---------------------------- |
| --json | boolean | Emit machine-readable output |

### Examples

`relkit` — Convention-first TypeScript application framework

### `relkit create [name]`

Create a new RelKit application

| Argument | Value    | Description                      |
| -------- | -------- | -------------------------------- |
| name     | optional | npm package and application name |

| Option                  | Value                                            | Description                                              |
| ----------------------- | ------------------------------------------------ | -------------------------------------------------------- |
| --template              | minimal, api, agent, fullstack, tasks            | Starter template                                         |
| --cloud                 | aws, none                                        | Cloud selection                                          |
| --deploy                | pulumi, none                                     | Deployment selection                                     |
| --jobs                  | inngest-docker, effect-mq-docker, trigger-docker | Jobs service for the tasks template                      |
| --directory             | string                                           | Destination directory                                    |
| --install               | boolean                                          | Install generated project setup                          |
| --no-install            | boolean                                          | No install generated project setup                       |
| --git                   | boolean                                          | Git generated project setup                              |
| --no-git                | boolean                                          | No git generated project setup                           |
| --examples              | boolean                                          | Examples generated project setup                         |
| --no-examples           | boolean                                          | No examples generated project setup                      |
| --force-empty-directory | boolean                                          | Allow an existing empty destination                      |
| --strict                | boolean                                          | Refuse combinations CI has not tested instead of warning |

#### Examples

`relkit create my-app` — Create an application named `my-app` and install its packages

`relkit create my-app --template fullstack` — Start from the fullstack template instead of the default

`relkit create my-app --no-install --no-git` — Write the files only, without installing packages or starting a Git repository

### `relkit add <kind>`

Add a compile-ready artifact

#### Examples

`relkit add service orders` — Create an `orders` service in `src/services`

`relkit add function create-order --service orders` — Add a function to the `orders` service

`relkit add inspector` — Install the development inspector and its local UI

#### `relkit add service [name]`

Create a domain service

| Argument | Value    | Description  |
| -------- | -------- | ------------ |
| name     | optional | Service name |

| Option           | Value                                                                                                   | Description                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string                                                                                                  | Application directory (defaults to cwd)                                                          |
| --service        | string                                                                                                  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string                                                                                                  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean                                                                                                 | Do not install newly required packages                                                           |
| --full           | boolean                                                                                                 | Create the complete deterministic domain bundle; exclusive with --include                        |
| --include        | function, task, error, event, event-function, job, cache, bucket, tool, prompt, agent, constants, route | Artifact kind to include; repeatable                                                             |

##### Examples

`relkit add service` — Create a domain service

#### `relkit add function [name]`

Create a callable function

| Argument | Value    | Description   |
| -------- | -------- | ------------- |
| name     | optional | Function name |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |
| --internal       | boolean | Keep the artifact out of the public service API                                                  |

##### Examples

`relkit add function` — Create a callable function

#### `relkit add task [name]`

Create a task artifact

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Task name   |

| Option           | Value              | Description                                                                                      |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------ |
| --project-root   | string             | Application directory (defaults to cwd)                                                          |
| --service        | string             | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string             | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean            | Do not install newly required packages                                                           |
| --version        | string             | Task semantic version (default: 1)                                                               |
| --execution      | durable, retryable | Task execution model (default: durable)                                                          |

##### Examples

`relkit add task` — Create a task artifact

#### `relkit add error [name]`

Create an internal typed error

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Error name  |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |

##### Examples

`relkit add error` — Create an internal typed error

#### `relkit add event [name]`

Create an event contract

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Event name  |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |
| --internal       | boolean | Keep the artifact out of the public service API                                                  |
| --profile        | string  | Compatible profile name; otherwise reuse a default/unique profile or scaffold a local profile    |

##### Examples

`relkit add event` — Create an event contract

#### `relkit add event-function [name]`

Create an event-only function

| Argument | Value    | Description         |
| -------- | -------- | ------------------- |
| name     | optional | Event function name |

| Option           | Value              | Description                                                                                      |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------ |
| --project-root   | string             | Application directory (defaults to cwd)                                                          |
| --service        | string             | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string             | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean            | Do not install newly required packages                                                           |
| --event          | string             | Event ID, binding, or filename                                                                   |
| --delivery       | transient, durable | Delivery mode (default: durable)                                                                 |
| --profile        | string             | Compatible profile name; otherwise reuse a default/unique profile or scaffold a local profile    |

##### Examples

`relkit add event-function` — Create an event-only function

#### `relkit add job [name]`

Create an unscheduled single-attempt job

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Job name    |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |
| --target         | string  | Task ID; legacy callable function targets remain readable                                        |
| --profile        | string  | Compatible profile name; otherwise reuse a default/unique profile or scaffold a local profile    |

##### Examples

`relkit add job` — Create an unscheduled single-attempt job

#### `relkit add cache [name]`

Create a cache descriptor and compatible profile

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Cache name  |

| Option           | Value                  | Description                                                                                      |
| ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string                 | Application directory (defaults to cwd)                                                          |
| --service        | string                 | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string                 | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean                | Do not install newly required packages                                                           |
| --profile        | string                 | Compatible profile name; otherwise reuse a default/unique profile or scaffold a local profile    |
| --provider       | redis, cloudflare-kv   | Cache provider                                                                                   |
| --source         | docker, connected, aws | Provider source                                                                                  |

##### Examples

`relkit add cache` — Create a cache descriptor and compatible profile

#### `relkit add bucket [name]`

Create a bucket descriptor and compatible profile

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Bucket name |

| Option           | Value                  | Description                                                                                      |
| ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string                 | Application directory (defaults to cwd)                                                          |
| --service        | string                 | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string                 | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean                | Do not install newly required packages                                                           |
| --profile        | string                 | Compatible profile name; otherwise reuse a default/unique profile or scaffold a local profile    |
| --provider       | s3, cloudflare-r2      | Bucket provider                                                                                  |
| --source         | docker, connected, aws | Provider source                                                                                  |

##### Examples

`relkit add bucket` — Create a bucket descriptor and compatible profile

#### `relkit add tool [name]`

Expose a callable function as an agent tool

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Tool name   |

| Option            | Value                       | Description                                                                                      |
| ----------------- | --------------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root    | string                      | Application directory (defaults to cwd)                                                          |
| --service         | string                      | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service  | string                      | Create and use a new generic service for a domain artifact or service route                      |
| --no-install      | boolean                     | Do not install newly required packages                                                           |
| --target          | string                      | Existing callable function; exclusive with --create-function                                     |
| --create-function | string                      | Create a callable function; exclusive with --target                                              |
| --side-effect     | none, read, write, external | Tool side-effect class (default: read)                                                           |
| --approval        | never, on-write, always     | Tool approval policy (default: never)                                                            |

##### Examples

`relkit add tool` — Expose a callable function as an agent tool

#### `relkit add prompt [name]`

Create a reusable prompt

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Prompt name |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |
| --text           | string  | Prompt text; repeatable                                                                          |

##### Examples

`relkit add prompt` — Create a reusable prompt

#### `relkit add agent [name]`

Create an agent with a model, tools, and instructions

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Agent name  |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |
| --model          | string  | Existing native model profile; omitted uses an offline model                                     |
| --tool           | string  | Tool ID, binding, or filename; repeatable                                                        |
| --prompt         | string  | Service prompt ID, binding, or filename; exclusive with --instructions                           |
| --instructions   | string  | Inline instructions; exactly one of --prompt or --instructions is required                       |

##### Examples

`relkit add agent` — Create an agent with a model, tools, and instructions

#### `relkit add constants [name]`

Create a constants descriptor

| Argument | Value    | Description    |
| -------- | -------- | -------------- |
| name     | optional | Constants name |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |

##### Examples

`relkit add constants` — Create a constants descriptor

#### `relkit add route [path]`

Create a route or service route

| Argument | Value    | Description    |
| -------- | -------- | -------------- |
| path     | optional | URL route path |

| Option           | Value                | Description                                                                                      |
| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string               | Application directory (defaults to cwd)                                                          |
| --service        | string               | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string               | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean              | Do not install newly required packages                                                           |
| --mode           | route, service-route | Required headlessly: raw GET route or public service-member mappings                             |
| --map            | key=value            | METHOD=member mapping; repeatable                                                                |

##### Examples

`relkit add route` — Create a route or service route

#### `relkit add middleware [name]`

Create pass-through route middleware

| Argument | Value    | Description     |
| -------- | -------- | --------------- |
| name     | optional | Middleware name |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |
| --path           | string  | Validated middleware route scope                                                                 |

##### Examples

`relkit add middleware` — Create pass-through route middleware

#### `relkit add transform [name]`

Create a string request transform

| Argument | Value    | Description    |
| -------- | -------- | -------------- |
| name     | optional | Transform name |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |

##### Examples

`relkit add transform` — Create a string request transform

#### `relkit add database`

Create the singleton Drizzle database service

| Option           | Value                     | Description                                                                                      |
| ---------------- | ------------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string                    | Application directory (defaults to cwd)                                                          |
| --service        | string                    | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string                    | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean                   | Do not install newly required packages                                                           |
| --orm            | drizzle                   | Database ORM                                                                                     |
| --dialect        | sqlite, postgresql, mysql | Database dialect (default: sqlite)                                                               |

##### Examples

`relkit add database` — Create the singleton Drizzle database service

#### `relkit add auth`

Create Better Auth and its catch-all route

| Option             | Value                     | Description                                                                                      |
| ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root     | string                    | Application directory (defaults to cwd)                                                          |
| --service          | string                    | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service   | string                    | Create and use a new generic service for a domain artifact or service route                      |
| --no-install       | boolean                   | Do not install newly required packages                                                           |
| --adapter          | better-auth               | Authentication adapter                                                                           |
| --database-dialect | sqlite, postgresql, mysql | Database dialect when one must be created (default: sqlite)                                      |
| --base-path        | string                    | Auth base path (default: /api/auth)                                                              |

##### Examples

`relkit add auth` — Create Better Auth and its catch-all route

#### `relkit add jobs`

Add a jobs provider profile

| Option         | Value           | Description                               |
| -------------- | --------------- | ----------------------------------------- |
| --project-root | string          | Application directory (defaults to cwd)   |
| --no-install   | boolean         | Do not install newly required packages    |
| --provider     | postgres, local | Provider (default: local)                 |
| --profile      | string          | Profile name (default: the provider name) |

##### Examples

`relkit add jobs` — Add a jobs provider profile

#### `relkit add events`

Add an events provider profile

| Option         | Value           | Description                               |
| -------------- | --------------- | ----------------------------------------- |
| --project-root | string          | Application directory (defaults to cwd)   |
| --no-install   | boolean         | Do not install newly required packages    |
| --provider     | postgres, local | Provider (default: local)                 |
| --profile      | string          | Profile name (default: the provider name) |

##### Examples

`relkit add events` — Add an events provider profile

#### `relkit add inspector`

Enable the inspector bridge and its local UI

| Option         | Value   | Description                             |
| -------------- | ------- | --------------------------------------- |
| --project-root | string  | Application directory (defaults to cwd) |
| --no-install   | boolean | Do not install @relkit/inspector        |

##### Examples

`relkit add inspector` — Enable the inspector bridge and its local UI

### `relkit migrate [--write | --rollback <record>]`

Preview and apply the 0.9 code migration, or layout migrations

| Option         | Value   | Description                                                                      |
| -------------- | ------- | -------------------------------------------------------------------------------- |
| --project-root | string  | Application directory (defaults to cwd)                                          |
| --write        | boolean | Apply the previewed changes and write a migration record                         |
| --rollback     | string  | Restore files from a migration record; refuses to overwrite later edits          |
| --contract     | string  | Client contract (client-contract.json) used to name api properties for hook keys |

#### Examples

`relkit migrate` — Preview and apply the 0.9 code migration, or layout migrations

#### `relkit migrate layout`

Move flat services into src/services with guarded rollback

| Option         | Value   | Description                                                             |
| -------------- | ------- | ----------------------------------------------------------------------- |
| --project-root | string  | Application directory (defaults to cwd)                                 |
| --write        | boolean | Validate and apply; stop development first                              |
| --rollback     | string  | Restore files from a migration record; refuses to overwrite later edits |

##### Examples

`relkit migrate layout` — Move flat services into src/services with guarded rollback

### `relkit db <command>`

Manage application database migrations

#### Examples

`relkit db` — Manage application database migrations

#### `relkit db migrate`

Apply pending migrations using the application's installed tools

| Option   | Value  | Description                                                                                                                                                                                                                                                                         |
| -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| --config | string | Application Drizzle config; defaults to drizzle.config.ts. Relative paths use the application root. The config reads the process environment and the application's .env, .env.&lt;mode>, .env.local and .env.&lt;mode>.local files; a value already in the process environment wins |

##### Examples

`relkit db migrate` — Apply the pending migrations with the project's Drizzle configuration

`relkit db migrate --config ./drizzle.staging.config.ts` — Use another Drizzle configuration file

### `relkit dev`

Run the app and its selected development features

| Option           | Value                                             | Description                                                                  |
| ---------------- | ------------------------------------------------- | ---------------------------------------------------------------------------- |
| --project-root   | string                                            | Application directory (defaults to cwd)                                      |
| --prepare        | boolean                                           | Check the project and exit without starting a server                         |
| --port           | integer                                           | Application port                                                             |
| --inspector-port | integer                                           | Retired; configure inspector.connection.port, or run relkit inspector --port |
| --local          | on, off                                           | Start required local services                                                |
| --log-level      | all, trace, debug, info, warn, error, fatal, none | Minimum terminal severity (default: info)                                    |
| --verbose        | boolean                                           | Show debug events and full retained diagnostics                              |
| --no-color       | boolean                                           | Disable terminal colors                                                      |

#### Examples

`relkit dev` — Run the application and rebuild it on every save

`relkit dev --port 4100` — Serve the application on port 4100

`relkit dev --project-root ./apps/api --log-level debug` — Run another application in the repository and show debug events

### `relkit inspector`

Run the project-local development inspector UI

| Option         | Value   | Description                                 |
| -------------- | ------- | ------------------------------------------- |
| --project-root | string  | Application directory (defaults to cwd)     |
| --port         | integer | Inspector UI port (default: 3210)           |
| --hostname     | string  | Inspector UI bind host (default: 127.0.0.1) |

#### Examples

`relkit inspector` — Open the inspector UI on port 3210 for the project in the current folder

`relkit inspector --port 3211 --project-root ./apps/api` — Serve the inspector for another application on another port

### `relkit mcp`

Serve the running development session to coding agents over MCP (stdio)

| Option         | Value  | Description                             |
| -------------- | ------ | --------------------------------------- |
| --project-root | string | Application directory (defaults to cwd) |

#### Examples

`relkit mcp` — Serve the running development session to coding agents over MCP (stdio)

### `relkit check`

Compile descriptors, infer eligible IDs, and validate the application

| Option            | Value   | Description                                                                                 |
| ----------------- | ------- | ------------------------------------------------------------------------------------------- |
| --project-root    | string  | Application directory (defaults to cwd)                                                     |
| --include-outputs | boolean | With --json, include the text of every generated file; paths and hashes are always included |

#### Examples

`relkit check` — Check the application in the current folder

`relkit check --project-root ./apps/api` — Check another application in the repository

`relkit check --json --include-outputs` — Print the result as JSON with the text of every generated file

### `relkit build`

Build the checked graph, manifest, OpenAPI, and client

| Option         | Value              | Description                                                                                                |
| -------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- |
| --project-root | string             | Application directory (defaults to cwd)                                                                    |
| --runtime      | bun, node, workers | Runtime the production server runs on (default: node when relkit runs on Node.js, bun when it runs on Bun) |
| --target       | vercel             | Deploy target whose build rules apply                                                                      |

#### Examples

`relkit build` — Build the application for the runtime that runs relkit

`relkit build --runtime node` — Build a Node.js server, whichever runtime runs relkit

`relkit build --target vercel` — Build for Vercel, which runs the Node.js server

### `relkit start`

Start the built application; run `relkit build` first

| Option         | Value   | Description                             |
| -------------- | ------- | --------------------------------------- |
| --project-root | string  | Application directory (defaults to cwd) |
| --port         | integer | Application port                        |

#### Examples

`relkit start` — Start the build in `.relkit/build`; it fails until `relkit build` has succeeded

`relkit start --port 8080` — Start the existing build on port 8080

`relkit start --project-root ./apps/api` — Start the build of another application in the repository

### `relkit graph <command>`

Inspect deterministic application graphs

#### Examples

`relkit graph print .relkit/build/application.graph.json` — Print the built application graph

`relkit graph diff before.graph.json after.graph.json` — Compare two graphs and list the compatibility changes

#### `relkit graph print [graph]`

Print a canonical graph with services and resolved source IDs

| Argument | Value    | Description     |
| -------- | -------- | --------------- |
| graph    | optional | Graph JSON path |

| Option         | Value  | Description                             |
| -------------- | ------ | --------------------------------------- |
| --project-root | string | Application directory (defaults to cwd) |

##### Examples

`relkit graph print` — Print a canonical graph with services and resolved source IDs

#### `relkit graph check [graph]`

Validate a graph and optional hash

| Argument | Value    | Description     |
| -------- | -------- | --------------- |
| graph    | optional | Graph JSON path |

| Option         | Value  | Description                             |
| -------------- | ------ | --------------------------------------- |
| --project-root | string | Application directory (defaults to cwd) |
| --hash         | string | Expected sha256 graph hash              |

##### Examples

`relkit graph check` — Validate a graph and optional hash

#### `relkit graph diff <before> <after>`

Compare graph compatibility, including inferred identity moves

| Argument | Value    | Description         |
| -------- | -------- | ------------------- |
| before   | required | Previous graph path |
| after    | required | Next graph path     |

| Option         | Value  | Description                             |
| -------------- | ------ | --------------------------------------- |
| --project-root | string | Application directory (defaults to cwd) |

##### Examples

`relkit graph diff` — Compare graph compatibility, including inferred identity moves

### `relkit env <command>`

Inspect value-free environment contracts

#### Examples

`relkit env check` — Check that every required environment variable has a value

`relkit env list --environment production` — List which variables are set for the production environment, without printing values

`relkit env example --write` — Write a safe `.env.example` for the project

#### `relkit env check`

Validate environment values

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |

##### Examples

`relkit env check` — Validate environment values

#### `relkit env list`

List environment value status

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |

##### Examples

`relkit env list` — List environment value status

#### `relkit env explain <name>`

Explain one environment variable

| Argument | Value    | Description               |
| -------- | -------- | ------------------------- |
| name     | required | Environment variable name |

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |

##### Examples

`relkit env explain` — Explain one environment variable

#### `relkit env example`

Render or write a safe .env example

| Option                | Value   | Description                             |
| --------------------- | ------- | --------------------------------------- |
| --project-root        | string  | Application directory (defaults to cwd) |
| --environment / --env | string  | Provider environment configuration      |
| --path / --file       | string  | Output path                             |
| --write               | boolean | Write the rendered example              |

##### Examples

`relkit env example` — Render or write a safe .env example

### `relkit local <command>`

Manage project-scoped local services

#### Examples

`relkit local up` — Start the local services the application declares

`relkit local status` — Show which local services run and who holds them

`relkit local reset --dry-run` — List what a reset would remove, and remove nothing

#### `relkit local up`

Start all declared local services

| Option                | Value   | Description                             |
| --------------------- | ------- | --------------------------------------- |
| --project-root        | string  | Application directory (defaults to cwd) |
| --environment / --env | string  | Provider environment configuration      |
| --service             | string  | Limit to one service binding            |
| --detach              | boolean | Keep services running after exit        |

##### Examples

`relkit local up` — Start all declared local services

#### `relkit local status`

Show local service and lease status

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Limit to one service binding            |

##### Examples

`relkit local status` — Show local service and lease status

#### `relkit local stop`

Stop project local containers and preserve volumes

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Limit to one service binding            |

##### Examples

`relkit local stop` — Stop project local containers and preserve volumes

#### `relkit local reset`

Remove project local containers, volumes, and state

| Option                | Value   | Description                                |
| --------------------- | ------- | ------------------------------------------ |
| --project-root        | string  | Application directory (defaults to cwd)    |
| --environment / --env | string  | Provider environment configuration         |
| --service             | string  | Limit to one service binding               |
| --yes                 | boolean | Confirm reset without prompting            |
| --dry-run             | boolean | Show owned resources without removing them |

##### Examples

`relkit local reset` — Remove project local containers, volumes, and state

### `relkit jobs <command>`

Inspect and operate task-backed jobs

#### Examples

`relkit jobs list` — List the jobs the application defines

`relkit jobs trigger --job orders.send --input-file ./input.json` — Run a job with the input in a JSON file

`relkit jobs runs list` — List the runs the jobs service accepted

#### `relkit jobs list`

List compiled job definitions

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |

##### Examples

`relkit jobs list` — List compiled job definitions

#### `relkit jobs runs <command>`

Inspect accepted job runs

##### Examples

`relkit jobs runs` — Inspect accepted job runs

##### `relkit jobs runs list`

List runs with native filters

| Option                | Value                                                                          | Description                             |
| --------------------- | ------------------------------------------------------------------------------ | --------------------------------------- |
| --project-root        | string                                                                         | Application directory (defaults to cwd) |
| --environment / --env | string                                                                         | Provider environment configuration      |
| --service             | string                                                                         | Jobs service profile                    |
| --job                 | string                                                                         | Job name or ID                          |
| --task-id             | string                                                                         | Task ID                                 |
| --status              | accepted, running, sleeping, retrying, completed, failed, cancelled, timed-out | Run status                              |
| --from                | string                                                                         | Lower time bound                        |
| --to                  | string                                                                         | Upper time bound                        |
| --tag                 | string                                                                         | Run tag; repeatable                     |
| --tag-match           | all, any                                                                       | Tag matching mode                       |
| --limit               | integer                                                                        | Rows (1-100)                            |
| --cursor              | string                                                                         | Opaque page cursor                      |

###### Examples

`relkit jobs runs list` — List runs with native filters

##### `relkit jobs runs get`

Read one run

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --run-id              | string | Opaque run locator                      |

###### Examples

`relkit jobs runs get` — Read one run

##### `relkit jobs runs watch`

Watch one run as newline-delimited frames

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --run-id              | string | Opaque run locator                      |
| --after               | string | Resume cursor                           |

###### Examples

`relkit jobs runs watch` — Watch one run as newline-delimited frames

#### `relkit jobs trigger`

Submit validated task input

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --job                 | string | Job name or ID                          |
| --input-file          | string | JSON input file                         |
| --idempotency-key     | string | External idempotency key                |
| --operation-id        | string | Stable operation ID                     |
| --delay               | string | Readable delay                          |
| --at                  | string | RFC3339 scheduled time                  |

##### Examples

`relkit jobs trigger` — Submit validated task input

#### `relkit jobs cancel`

Cancel one run

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --run-id              | string | Opaque run locator                      |
| --operation-id        | string | Required control operation ID           |
| --reason              | string | Cancellation reason                     |

##### Examples

`relkit jobs cancel` — Cancel one run

#### `relkit jobs retry`

Retry one terminal run

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --run-id              | string | Opaque run locator                      |
| --operation-id        | string | Required control operation ID           |

##### Examples

`relkit jobs retry` — Retry one terminal run

#### `relkit jobs capabilities`

Show provider capability reports

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |

##### Examples

`relkit jobs capabilities` — Show provider capability reports

#### `relkit jobs schedules <command>`

Administer native schedules

##### Examples

`relkit jobs schedules` — Administer native schedules

##### `relkit jobs schedules list`

List schedules

| Option                | Value   | Description                             |
| --------------------- | ------- | --------------------------------------- |
| --project-root        | string  | Application directory (defaults to cwd) |
| --environment / --env | string  | Provider environment configuration      |
| --service             | string  | Jobs service profile                    |
| --job                 | string  | Job name or ID                          |
| --limit               | integer | Rows (1-100)                            |
| --cursor              | string  | Opaque page cursor                      |

###### Examples

`relkit jobs schedules list` — List schedules

##### `relkit jobs schedules get`

Read one schedule

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --schedule-id         | string | Schedule ID                             |

###### Examples

`relkit jobs schedules get` — Read one schedule

##### `relkit jobs schedules upsert`

Create or update a schedule

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --schedule-id         | string | Schedule ID                             |
| --definition-file     | string | JSON definition file                    |
| --operation-id        | string | Stable operation ID                     |

###### Examples

`relkit jobs schedules upsert` — Create or update a schedule

##### `relkit jobs schedules pause`

Pause a schedule

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --schedule-id         | string | Schedule ID                             |
| --operation-id        | string | Stable operation ID                     |

###### Examples

`relkit jobs schedules pause` — Pause a schedule

##### `relkit jobs schedules resume`

Resume a schedule

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --schedule-id         | string | Schedule ID                             |
| --operation-id        | string | Stable operation ID                     |

###### Examples

`relkit jobs schedules resume` — Resume a schedule

##### `relkit jobs schedules delete`

Delete a schedule

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --schedule-id         | string | Schedule ID                             |
| --operation-id        | string | Stable operation ID                     |

###### Examples

`relkit jobs schedules delete` — Delete a schedule

### `relkit doctor`

Check local prerequisites and ports

| Option           | Value   | Description                                                             |
| ---------------- | ------- | ----------------------------------------------------------------------- |
| --project-root   | string  | Application directory (defaults to cwd)                                 |
| --port           | integer | Application port                                                        |
| --inspector-port | integer | Retired; configure inspector.connection.port for the application bridge |
| --no-ports       | boolean | Skip port availability checks                                           |
| --pulumi         | boolean | Require Pulumi                                                          |
| --no-pulumi      | boolean | Skip Pulumi requirements                                                |

#### Examples

`relkit doctor` — Check the tools and ports the application needs

`relkit doctor --port 4100` — Check that port 4100 is free for the application

`relkit doctor --no-ports` — Check the tools only, without testing ports

### `relkit deploy <command>`

Manage deployments

#### Examples

`relkit deploy` — Manage deployments

#### `relkit deploy init [target]`

Write a deploy target's files, or initialize the Pulumi stack

| Argument | Value    | Description                                                             |
| -------- | -------- | ----------------------------------------------------------------------- |
| target   | optional | railway, vercel, cloudflare, or aws for the Pulumi stack (default: aws) |

| Option                    | Value              | Description                                                              |
| ------------------------- | ------------------ | ------------------------------------------------------------------------ |
| --project-root            | string             | Application directory (defaults to cwd)                                  |
| --stack                   | string             | Pulumi stack name (default: development)                                 |
| --backend                 | string             | cloud, local, or object-storage URL                                      |
| --config                  | key=value          | Set a non-secret Pulumi value; repeatable                                |
| --config-secret           | key=value          | Set a secret Pulumi value; repeatable                                    |
| --non-interactive / --yes | boolean            | Approve protected operations                                             |
| --runtime                 | bun, node, workers | Server runtime (railway: bun or node; vercel: node; cloudflare: workers) |
| --force                   | boolean            | Replace existing deploy files that differ (railway, vercel, cloudflare)  |

##### Examples

`relkit deploy init` — Write a deploy target's files, or initialize the Pulumi stack

#### `relkit deploy preview`

Preview the Pulumi stack

| Option                    | Value     | Description                               |
| ------------------------- | --------- | ----------------------------------------- |
| --project-root            | string    | Application directory (defaults to cwd)   |
| --stack                   | string    | Pulumi stack name (default: development)  |
| --backend                 | string    | cloud, local, or object-storage URL       |
| --config                  | key=value | Set a non-secret Pulumi value; repeatable |
| --config-secret           | key=value | Set a secret Pulumi value; repeatable     |
| --non-interactive / --yes | boolean   | Approve protected operations              |

##### Examples

`relkit deploy preview` — Preview the Pulumi stack

#### `relkit deploy up`

Up the Pulumi stack

| Option                    | Value     | Description                               |
| ------------------------- | --------- | ----------------------------------------- |
| --project-root            | string    | Application directory (defaults to cwd)   |
| --stack                   | string    | Pulumi stack name (default: development)  |
| --backend                 | string    | cloud, local, or object-storage URL       |
| --config                  | key=value | Set a non-secret Pulumi value; repeatable |
| --config-secret           | key=value | Set a secret Pulumi value; repeatable     |
| --non-interactive / --yes | boolean   | Approve protected operations              |

##### Examples

`relkit deploy up` — Up the Pulumi stack

#### `relkit deploy refresh`

Refresh the Pulumi stack

| Option                    | Value     | Description                               |
| ------------------------- | --------- | ----------------------------------------- |
| --project-root            | string    | Application directory (defaults to cwd)   |
| --stack                   | string    | Pulumi stack name (default: development)  |
| --backend                 | string    | cloud, local, or object-storage URL       |
| --config                  | key=value | Set a non-secret Pulumi value; repeatable |
| --config-secret           | key=value | Set a secret Pulumi value; repeatable     |
| --non-interactive / --yes | boolean   | Approve protected operations              |

##### Examples

`relkit deploy refresh` — Refresh the Pulumi stack

#### `relkit deploy outputs`

Outputs the Pulumi stack

| Option                    | Value     | Description                               |
| ------------------------- | --------- | ----------------------------------------- |
| --project-root            | string    | Application directory (defaults to cwd)   |
| --stack                   | string    | Pulumi stack name (default: development)  |
| --backend                 | string    | cloud, local, or object-storage URL       |
| --config                  | key=value | Set a non-secret Pulumi value; repeatable |
| --config-secret           | key=value | Set a secret Pulumi value; repeatable     |
| --non-interactive / --yes | boolean   | Approve protected operations              |

##### Examples

`relkit deploy outputs` — Outputs the Pulumi stack

#### `relkit deploy destroy`

Destroy the Pulumi stack

| Option                    | Value     | Description                               |
| ------------------------- | --------- | ----------------------------------------- |
| --project-root            | string    | Application directory (defaults to cwd)   |
| --stack                   | string    | Pulumi stack name (default: development)  |
| --backend                 | string    | cloud, local, or object-storage URL       |
| --config                  | key=value | Set a non-secret Pulumi value; repeatable |
| --config-secret           | key=value | Set a secret Pulumi value; repeatable     |
| --non-interactive / --yes | boolean   | Approve protected operations              |

##### Examples

`relkit deploy destroy` — Destroy the Pulumi stack

### `relkit client <command>`

Generate a client from a running application

#### Examples

`relkit client` — Generate a client from a running application

#### `relkit client pull <baseUrl> --out <directory>`

Pull a versioned client contract

| Argument | Value    | Description                    |
| -------- | -------- | ------------------------------ |
| baseUrl  | required | Running RelKit application URL |

| Option | Value  | Description      |
| ------ | ------ | ---------------- |
| --out  | string | Output directory |

##### Examples

`relkit client pull` — Pull a versioned client contract

#### `relkit client check <baseUrl> --out <directory>`

Check a pulled client for contract drift

| Argument | Value    | Description                    |
| -------- | -------- | ------------------------------ |
| baseUrl  | required | Running RelKit application URL |

| Option | Value  | Description      |
| ------ | ------ | ---------------- |
| --out  | string | Output directory |

##### Examples

`relkit client check` — Check a pulled client for contract drift
