Skip to content
RelKit
Esc
↑↓navigate↵open⌘Jpreview
On this page

CLI reference

Generated command, argument, flag, and example reference for relkit 0.9.2.

For guided setup and everyday workflows, start with the CLI module or follow 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.<mode>, .env.local and .env.<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