Reference

Options that are marked with a boolean type are command line flags that do not take a value, however their config file and environment variable equivalents do take a value that should be set to one of true, false, 1 or 0.

Global Options

--config

The path to the configuration file to source CLI configuration from. Relative paths are expected to be relative to the current working directory.

Type: string

Default Value: celerity.config.toml

--app-deploy-config-file

Environment Variable: CELERITY_CLI_APP_DEPLOY_CONFIG_FILE

Configuration Key: appDeployConfigFile

Type: string

Default Value: app.deploy.jsonc

The path to the app deploy configuration file that contains blueprint variable overrides and configuration for the target environment for a Celerity application. This file is expected to be in the JSON with Commas and Comments format described in the App Deploy Configuration doc.

This file is used by the stage, deploy, destroy and validate commands.

--connect-protocol

Environment Variable: CELERITY_CLI_CONNECT_PROTOCOL

Configuration Key: connectProtocol

Type: string

Default Value: unix

Allowed Values: unix | tcp

The protocol to connect to the deploy engine with, this can be either unix or tcp. A unix socket can only be used on linux, macos and other unix-like operating systems. To use a unix socket on windows, you will need to use WSL 2 or above.

--engine-endpoint

Environment Variable: CELERITY_CLI_ENGINE_ENDPOINT

Configuration Key: engineEndpoint

Type: string

Default Value: http://localhost:8325

The endpoint of the deploy engine api, this is used if --connect-protocol is set to tcp.

help

For information on all the available commands and global options, run the following:

celerity help

To get usage information for a specific command, run the following:

celerity [command] --help

validate

This command validates a Celerity project or blueprint file. It will validate source code, the project blueprint and other configuration files. It can also be used to validate a single blueprint file.

--blueprint-file

Environment Variable: CELERITY_CLI_VALIDATE_BLUEPRINT_FILE

Configuration Key: validateBlueprintFile

Default Value: auto-detect (app.bp, app.blueprint.yaml, or app.blueprint.jsonc)

--check-blueprint-vars

Environment Variable: CELERITY_CLI_VALIDATE_CHECK_BLUEPRINT_VARS

Configuration Key: validateCheckBlueprintVars

Type: boolean

Default Value: false

This flag enables validation of the blueprint variable values that are set in the deploy configuration file. By default, the CLI will not validate the blueprint variable overrides set in the deploy configuration file when validating a blueprint file.

--check-plugin-config

Environment Variable: CELERITY_CLI_VALIDATE_CHECK_PLUGIN_CONFIG

Configuration Key: validateCheckPluginConfig

Type: boolean

Default Value: false

By default, the validate command only runs validation on a provided blueprint file. You can use the --check-blueprint-vars flag to validate the blueprint variable values set in the deploy configuration file. By default, configuration specific to providers and transformers is not validated as a part of this command. When this flag is set, the provider and transformer configuration sourced from deploy config files will be validated against the plugin configuration schemas.

--transform-spec

Environment Variable: CELERITY_CLI_VALIDATE_TRANSFORM_SPEC

Configuration Key: validateTransformSpec

Type: boolean

Default Value: true

Run transformer plugins during validation so abstract resources are expanded into concrete resources for richer diagnostics. Required for transformer-driven workflows to produce meaningful validation output. When set to false, validation runs against the blueprint without transformation.

--validate-after-transform

Environment Variable: CELERITY_CLI_VALIDATE_AFTER_TRANSFORM

Configuration Key: validateValidateAfterTransform

Type: boolean

Default Value: false

After transformation, validate resources against the transformed blueprint shape. This catches resource-level issues that only surface once abstract resources have been expanded into their concrete forms, which is typically useful when diagnosing deployment-time issues. Has no effect unless --transform-spec is also true.

build

Builds a Celerity application into deployable artifacts (for the AWS serverless target: a shared app-code archive, an entry point, and dependency layers) and writes a build manifest to .celerity/build-manifest.json. The build target and app environment come from the app deploy config. build runs automatically before stage and deploy unless --skip-build is set.

--blueprint-file

Type: string

The blueprint file to read handler and runtime information from. Auto-detected (app.bp, app.blueprint.yaml, or app.blueprint.jsonc) when not provided.

stage

Creates a change set by computing the difference between a blueprint and the current state of an instance (or empty state for a new deployment). The change set is streamed and presented for review, and can then be applied with deploy.

--blueprint-file

Type: string

Default Value: app.blueprint.yaml

The blueprint file to stage. This can be a local file, a public https:// URL, or an object storage path (s3://, gcs://, azureblob://).

--instance-id

Type: string

The ID of an existing blueprint instance to stage changes for. When neither --instance-id nor --instance-name is provided, changes are staged for a new deployment.

--instance-name

Type: string

The user-defined name of an existing blueprint instance to stage changes for.

--destroy

Type: boolean

Stage changes for destroying an existing instance. Requires --instance-id or --instance-name.

--skip-drift-check

Type: boolean

Skip detection of external resource changes (drift) during staging.

--json

Type: boolean

Output the result as a single JSON object when the operation completes. Implies non-interactive mode (no TUI, no streaming text output), which is useful for CI/CD pipelines and scripting.

deploy

Applies a change set to a blueprint instance (new or existing) and streams deployment events in real time.

--change-set-id

Type: string

The change set to deploy. When omitted, use --stage to stage and deploy in one step.

--stage

Type: boolean

Stage changes first, then deploy the resulting change set.

--instance-id / --instance-name

Type: string

The existing blueprint instance to deploy to. When neither is provided, a new instance is created.

--auto-approve

Type: boolean

Automatically approve staged changes without prompting. Intended for CI/CD. Only applicable with --stage.

--auto-approve-code-only

Type: boolean

Automatically approve staged changes when only code-hosting resources are modified. Requires --stage; denied when any creates, deletes, or infrastructure changes are present.

--auto-rollback

Type: boolean

Automatically roll back on deployment failure.

--force

Type: boolean

Override a drift check that would otherwise block the deployment.

--skip-prompts

Type: boolean

Skip interactive prompts and use flag values directly. Requires all necessary flags to be provided (--instance-name or --instance-id, and either --stage or --change-set-id).

--json

Type: boolean

Output the result as a single JSON object when the operation completes. Implies non-interactive mode. In --json mode staged changes are auto-approved, so it is intended for CI/CD.

destroy

Destroys a deployed blueprint instance, removing its resources, child blueprints, and links, streaming events in real time.

--change-set-id

Type: string

The destroy change set to apply. When omitted, use --stage to stage a destroy change set first.

--stage

Type: boolean

Stage destroy changes first, then execute.

--instance-id / --instance-name

Type: string

The instance to destroy. One of these is required.

--auto-approve

Type: boolean

Automatically approve the staged destroy. Only applicable with --stage.

--force

Type: boolean

Override a state/drift conflict that would otherwise block the destroy.

--skip-prompts

Type: boolean

Skip interactive prompts and use flag values directly. Requires all necessary flags to be provided (--instance-name or --instance-id, and either --stage or --change-set-id).

--json

Type: boolean

Output the result as a single JSON object when the operation completes. Implies non-interactive mode, with staged destroy changes auto-approved.

init

This command initialises a new Celerity application project. It will take you through a series of prompts to create a new application project. You can provide command line options to skip parts of the interactive process of setting up a new application project.

celerity init [--template <template>] [--language <language>] [project-name]

The optional project-name argument is the directory the new project is created in. When omitted, you are prompted for it (or the current directory is used).

--template

Environment Variable: CELERITY_CLI_INIT_TEMPLATE

Configuration Key: initTemplate

The project template to generate from (for example simple-api). Templates scaffold a ready-to-run application with a blueprint and handler code. When omitted, you are prompted to choose a template.

--language

Environment Variable: CELERITY_CLI_INIT_LANGUAGE

Configuration Key: initLanguage

Allowed Values: nodejs | python | java | dotnet | go

The language or framework to use for a new Celerity project.

dev

This is the command category for local development of Celerity applications.

run

Start a Celerity application in the local development environment. This will set up all the required infrastructure locally (database containers, cache instances, queue emulators, etc.) and start the application runtime with your handlers.

By default, the command runs in the foreground streaming container logs to stdout. Use --detached to run in the background.

--blueprint-file, -b

Environment Variable: CELERITY_CLI_DEV_RUN_BLUEPRINT_FILE

Configuration Key: devRunBlueprintFile

Type: string

Default Value: auto-detect (app.bp, app.blueprint.yaml, or app.blueprint.jsonc)

The path to the blueprint file. Relative paths are relative to --app-dir.

--deploy-config, -d

Environment Variable: CELERITY_CLI_DEV_RUN_DEPLOY_CONFIG

Configuration Key: devRunDeployConfig

Type: string

Default Value: auto-detect (app.deploy.jsonc)

The path to the deploy config file. Used to determine the deploy target (e.g. aws, gcloud) which controls which local emulators are started.

--port, -p

Environment Variable: CELERITY_CLI_DEV_RUN_PORT

Configuration Key: devRunPort

Type: string

Default Value: 8080

The host port to expose the Celerity runtime on.

--app-dir

Environment Variable: CELERITY_CLI_DEV_RUN_APP_DIR

Configuration Key: devRunAppDir

Type: string

Default Value: .

The application root directory containing the blueprint, source code, and configuration.

--module-path

Environment Variable: CELERITY_CLI_DEV_RUN_MODULE_PATH

Configuration Key: devRunModulePath

Type: string

Default Value: auto-detect from runtime conventions

The module entry point for the application (e.g. src/app-module.ts for Node.js, src/app_module.py for Python).

--image

Environment Variable: CELERITY_CLI_DEV_RUN_IMAGE

Configuration Key: devRunImage

Type: string

Override the Docker image for the runtime container. When set, GHCR image resolution is skipped.

--service-name

Environment Variable: CELERITY_CLI_DEV_RUN_SERVICE_NAME

Configuration Key: devRunServiceName

Type: string

Default Value: directory name

Override the service name used for the Docker container and compose project.

--detached

Environment Variable: CELERITY_CLI_DEV_RUN_DETACHED

Configuration Key: devRunDetached

Type: boolean

Default Value: false

Run the dev environment in the background. Use celerity dev logs to stream logs and celerity dev stop to tear down.

--verbose, -v

Environment Variable: CELERITY_CLI_DEV_RUN_VERBOSE

Configuration Key: devRunVerbose

Type: boolean

Default Value: false

Enable debug logging in the Celerity runtime and SDK.

--no-local-auth

Environment Variable: CELERITY_CLI_DEV_RUN_NO_LOCAL_AUTH

Configuration Key: devRunNoLocalAuth

Type: boolean

Default Value: false

Do not override the blueprint JWT issuer with the local dev auth server. By default, the dev environment patches the blueprint to use a local auth server for convenience during development.

test

Run tests for a Celerity application with automatic infrastructure setup and teardown.

Infrastructure is started based on the test suites being run:

Multiple suites can be combined with commas (e.g. --suite unit,integration). Infrastructure is started based on the highest level required by the combined suites.

The test runner is auto-detected from your project files:

• Node.js: Detected from package.json scripts (test, test:unit, test:integration, test:api) and devDependencies (vitest, jest, ava).
• Python: Detected from pyproject.toml, pytest.ini, or setup.cfg. Uses virtualenv (.venv or venv) if present.

Use --test-command to override auto-detection with a custom command.

The CELERITY_TEST_BASE_URL environment variable is passed to the test process when API tests are running, set to http://localhost:{port}. Infrastructure endpoint environment variables (e.g. CELERITY_LOCAL_DATASTORE_ENDPOINT) are also passed so tests can connect to local services.

--blueprint-file, -b

Environment Variable: CELERITY_CLI_DEV_TEST_BLUEPRINT_FILE

Configuration Key: devTestBlueprintFile

Type: string

Default Value: auto-detect

The path to the blueprint file. Only needed when running integration or API tests (not unit tests).

--deploy-config, -d

Environment Variable: CELERITY_CLI_DEV_TEST_DEPLOY_CONFIG

Configuration Key: devTestDeployConfig

Type: string

Default Value: auto-detect

The path to the deploy config file.

--port, -p

Environment Variable: CELERITY_CLI_DEV_TEST_PORT

Configuration Key: devTestPort

Type: string

Default Value: 8081

The host port for the app container. Used by API tests via CELERITY_TEST_BASE_URL.

--app-dir

Environment Variable: CELERITY_CLI_DEV_TEST_APP_DIR

Configuration Key: devTestAppDir

Type: string

Default Value: .

The application root directory.

--module-path

Environment Variable: CELERITY_CLI_DEV_TEST_MODULE_PATH

Configuration Key: devTestModulePath

Type: string

Default Value: auto-detect

The module entry point for the application.

--image

Environment Variable: CELERITY_CLI_DEV_TEST_IMAGE

Configuration Key: devTestImage

Type: string

Override the Docker image for the runtime container.

--service-name

Environment Variable: CELERITY_CLI_DEV_TEST_SERVICE_NAME

Configuration Key: devTestServiceName

Type: string

Default Value: directory name

Override the service name.

--verbose, -v

Environment Variable: CELERITY_CLI_DEV_TEST_VERBOSE

Configuration Key: devTestVerbose

Type: boolean

Default Value: false

Enable debug logging.

--suite, -s

Environment Variable: CELERITY_CLI_DEV_TEST_SUITE

Configuration Key: devTestSuite

Type: string

Default Value: unit

Allowed Values: unit | integration | api

Comma-separated list of test suites to run. Controls which infrastructure is started and which test directories are included.

Test directories follow project structure conventions:

• unit → src/ (Node.js) or tests/unit/ (Python)
• integration → tests/integration/
• api → tests/api/

--coverage

Environment Variable: CELERITY_CLI_DEV_TEST_COVERAGE

Configuration Key: devTestCoverage

Type: boolean

Default Value: true

Enable coverage reporting. The coverage mechanism depends on the test framework (e.g. --coverage for vitest/jest, --cov for pytest).

--test-command

Environment Variable: CELERITY_CLI_DEV_TEST_COMMAND

Configuration Key: devTestCommand

Type: string

Override the auto-detected test command. When set, this command is executed directly via the shell instead of auto-detecting from project files. Infrastructure setup and teardown still apply based on --suite.

--health-timeout

Environment Variable: CELERITY_CLI_DEV_TEST_HEALTH_TIMEOUT

Configuration Key: devTestHealthTimeout

Type: string

Default Value: 60s

How long to wait for the app container to become healthy before running API tests. Accepts Go duration strings (e.g. 30s, 2m). For Python projects, the default is automatically increased to 3m to allow for dependency installation during container startup.

--health-path

Environment Variable: CELERITY_CLI_DEV_TEST_HEALTH_PATH

Configuration Key: devTestHealthPath

Type: string

Default Value: /runtime/health/check

The health check endpoint path used to determine when the app container is ready before running API tests.

--no-teardown

Environment Variable: CELERITY_CLI_DEV_TEST_NO_TEARDOWN

Configuration Key: devTestNoTeardown

Type: boolean

Default Value: false

Keep infrastructure running after tests complete. Useful for debugging test failures — you can inspect databases, check logs with celerity dev logs, etc.

--no-local-auth

Environment Variable: CELERITY_CLI_DEV_TEST_NO_LOCAL_AUTH

Configuration Key: devTestNoLocalAuth

Type: boolean

Default Value: false

Do not override the blueprint JWT issuer with the local dev auth server.

stop

Tear down the running dev environment by stopping the runtime container and all dependency services.

--app-dir

Environment Variable: CELERITY_CLI_DEV_STOP_APP_DIR

Configuration Key: devStopAppDir

Type: string

Default Value: .

The application root directory.

status

Display the current state of the local dev environment including container status, handlers, port, runtime, and uptime.

--app-dir

Environment Variable: CELERITY_CLI_DEV_STATUS_APP_DIR

Configuration Key: devStatusAppDir

Type: string

Default Value: .

The application root directory.

logs

Stream or filter logs from the running dev environment container.

Supports filtering by handler name and minimum log level. When running in a terminal, output is colored by log level. Log files are written to .celerity/logs/ alongside stdout streaming.

Use --sync to dump all logs to files without streaming to stdout.

--app-dir

Environment Variable: CELERITY_CLI_DEV_LOGS_APP_DIR

Configuration Key: devLogsAppDir

Type: string

Default Value: .

The application root directory.

--handler, -H

Configuration Key: devLogsHandler

Type: string

Filter logs by handler name. Matches any handler whose name contains the given substring.

--level, -l

Configuration Key: devLogsLevel

Type: string

Allowed Values: debug | info | warn | error

Minimum log level to display. Logs below this level are filtered out.

--follow, -f

Configuration Key: devLogsFollow

Type: boolean

Default Value: true

Follow log output in real time. Set to false to print existing logs and exit.

--tail, -n

Configuration Key: devLogsTail

Type: string

Default Value: 100

Number of historical log lines to show. Use all to show all available lines.

--since, -s

Configuration Key: devLogsSince

Type: string

Show logs since a timestamp or duration. Accepts Go duration strings (e.g. 5m, 1h) or RFC3339 timestamps (e.g. 2024-01-01T00:00:00Z).

--sync

Configuration Key: devLogsSync

Type: boolean

Default Value: false

Dump all logs to per-handler files in .celerity/logs/ and exit without streaming to stdout.

stubs

Manage over-the-wire HTTP service stubs backed by mountebank.

validate

Load and validate all stub YAML files in the stubs/ directory. Checks for YAML syntax errors, missing required fields, port conflicts, and duplicate config keys.

celerity dev stubs validate

--app-dir

Configuration Key: devStubsAppDir

Type: string

Default Value: .

The application root directory.

config

This is the command category for managing deployed application runtime configuration and secrets.

Running celerity config without a subcommand opens an interactive TUI session for browsing and managing config values across environments and stores. In non-interactive (headless) mode, use the subcommands directly.

The CLI reads the blueprint to discover celerity/config resources and their storage backends. Environment-specific deploy config files (app.deploy.{env}.jsonc) can point to different cloud accounts, profiles, and regions. When no environment-specific file exists, the CLI falls back to the base app.deploy.jsonc and uses credentials from the current environment.

Common Options

--env, -e

Environment Variable: CELERITY_CLI_CONFIG_ENV

Configuration Key: configEnv

Type: string

Environment name. Loads app.deploy.{env}.jsonc if it exists, otherwise falls back to app.deploy.jsonc with {env} as the store name prefix. Required in non-interactive mode.

--app-dir

Environment Variable: CELERITY_CLI_CONFIG_APP_DIR

Configuration Key: configAppDir

Type: string

Default Value: .

The application root directory.

--blueprint-file, -b

Environment Variable: CELERITY_CLI_CONFIG_BLUEPRINT_FILE

Configuration Key: configBlueprintFile

Type: string

Default Value: auto-detect (app.bp, app.blueprint.yaml, or app.blueprint.jsonc)

The path to the blueprint file.

--region

Environment Variable: CELERITY_CLI_CONFIG_REGION

Configuration Key: configRegion

Type: string

Cloud provider region override. Takes precedence over the region specified in the deploy config file.

set

Set a config value in a deployed store. If value is omitted and the key is sensitive, you will be prompted for masked input in interactive mode, or the value is read from stdin in headless mode.

celerity config set <store> <key> [value] --env <environment>

--secret, -s

Environment Variable: CELERITY_CLI_CONFIG_SET_SECRET

Configuration Key: configSetSecret

Type: boolean

Default Value: false

Mark value as sensitive. In Parameter Store, this forces SecureString type even if the key is in the blueprint's plaintext list.

get

Get a single config value from a deployed store. Outputs the raw value to stdout for scripting.

celerity config get <store> <key> --env <environment>

list

Without a store argument, lists all celerity/config resources from the blueprint. With a store argument, lists all keys in that store.

celerity config list --env <environment>
celerity config list <store> --env <environment>

--show-secrets

Environment Variable: CELERITY_CLI_CONFIG_LIST_SHOW_SECRETS

Configuration Key: configListShowSecrets

Type: boolean

Default Value: false

Reveal masked values. By default, sensitive values are displayed as ********.

delete

Delete a config value from a deployed store. Prompts for confirmation in interactive mode.

celerity config delete <store> <key> --env <environment>

--yes, -y

Environment Variable: CELERITY_CLI_CONFIG_DELETE_YES

Configuration Key: configDeleteYes

Type: boolean

Default Value: false

Skip confirmation prompt. Required in non-interactive (headless) mode.

import

Import config values from a YAML or JSON file into a deployed store. Values are merged with existing entries by default.

celerity config import <store> <file> --env <environment>

export

Export config values from a deployed store to stdout or a file.

celerity config export <store> --env <environment>
celerity config export <store> --env <environment> --format json -o backup.json

--format

Environment Variable: CELERITY_CLI_CONFIG_EXPORT_FORMAT

Configuration Key: configExportFormat

Type: string

Default Value: yaml

Allowed Values: yaml | json

Output format for the exported data.

-o

Environment Variable: CELERITY_CLI_CONFIG_EXPORT_OUT

Configuration Key: configExportOut

Type: string

Output file path. If not specified, output is written to stdout.

schema

This is the command category for managing SQL database and NoSQL datastore schemas in Celerity applications.

See the SQL Database Schema Management guide for SQL databases and the NoSQL Datastore Schema Management guide for NoSQL datastores.

diff

Show pending schema changes and their contract impact and, for SQL databases, generate a migration file capturing them.

• SQL databases: Compares the desired state (schema YAML) against the current state (computed by replaying the migration directory on a temporary local database) and writes the difference as a new timestamped SQL migration file in migrationsPath, ready for review and commit. Diffing is powered by the embedded open-source Atlas engine; Celerity augments the generated SQL with data-aware transitions (e.g. backfills before NOT NULL constraints) and emits CREATE EXTENSION statements for extensions declared in the schema YAML. If there is no difference, no file is written.
• NoSQL datastores: Shows field-level changes (added, removed, type changed), reported per entity for single-table schemas, and pending escape hatch data scripts. No migration file or DDL is generated — field changes are application-layer only.

The output also includes:

• Pending migration files not yet applied to the target environment
• Contract impact analysis (which contracts would be satisfied or broken)
• Warnings for ambiguous or destructive changes; a generated destructive migration (drop table/column) is classified breaking and is not applied by celerity schema apply without --allow-breaking

celerity schema diff
celerity schema diff --name add_customer_tier

--name

Type: string

Description used in the generated migration file name (SQL databases only). Defaults to a summary derived from the changes.

--env

Environment Variable: CELERITY_CLI_SCHEMA_ENV

Configuration Key: schemaEnv

Type: string

The target environment to diff against. When specified, pending migrations are reported relative to the deployed schema state for that environment.

new

Create an empty timestamped migration file for hand-written SQL (SQL databases only) and update the migration directory integrity file (atlas.sum). Use this for structural SQL the schema YAML cannot express — triggers, functions, row-level security policies, partitioning, specialised indexes.

celerity schema new add_audit_trigger

The first positional argument is the description used in the migration file name.

--database

Type: string

The name of the celerity/sqlDatabase resource to create the migration for. Required when the blueprint contains more than one SQL database resource.

apply

Apply schema changes outside of a full deployment.

• SQL databases: Verifies migration directory integrity (atlas.sum), runs a pre-apply drift check against the target database, then applies pending migration files in timestamp order, recording each in the revision table.
• NoSQL datastores: Updates the schema state only — no database connection is made. Field-level changes are enforced at the application layer via SDK validation and generated types, not via database operations. Escape hatch data scripts are NOT auto-executed (they may take hours for large datasets).

celerity schema apply

--env

Environment Variable: CELERITY_CLI_SCHEMA_APPLY_ENV

Configuration Key: schemaApplyEnv

Type: string

The target environment to apply migrations to.

--auto-approve

Type: boolean

Default Value: false

Skip the interactive confirmation prompt and apply migrations immediately. Use with caution.

--allow-drift

Type: boolean

Default Value: false

Proceed with applying migrations even if the pre-apply drift check detects that the live database does not match the expected starting state. Use only once the drift has been reviewed and understood.

drift

Check a live SQL database or NoSQL datastore for drift against the schema. The command exits with a non-zero exit code when drift is detected, making it suitable for scheduled CI jobs, and matches drifted tables/datastores against schema-contracts.yaml so the report shows which downstream contracts are affected.

SQL databases — out-of-band structural changes, checked at three layers (see Drift Detection):

• History drift: The revision table is compared against the migration directory — migrations applied out-of-band, missing or applied out of order
• Structural drift: The live database is inspected and diffed against the expected state for everything the schema YAML models (tables, columns, indexes, foreign keys, constraints), reported as a full object-level diff
• Advanced-object drift: Objects created by hand-written migrations (triggers, functions, views, row-level security policies) are fingerprinted from the database catalog and flagged when changed, missing or unexpected

NoSQL datastores — data-shape drift via a sampled read-only scan of live items (see Drift Detection):

• Conformance drift: items not conforming to the schema (missing required fields, type mismatches, unexpected nulls) with per-field conformance percentages
• Unknown-field drift: fields present in sampled items but absent from the schema YAML
• When the schema defines entities, items are bucketed by discriminator value and reported per entity

celerity schema drift ordersDb --env production
celerity schema drift userStore --env production --sample 10000

The first positional argument is the name of the celerity/sqlDatabase or celerity/datastore resource in the blueprint.

--env

Environment Variable: CELERITY_CLI_SCHEMA_DRIFT_ENV

Configuration Key: schemaDriftEnv

Type: string

The target environment to check for drift. Required.

--sample

Type: integer

Default Value: 1000

The number of items to sample in the scan (NoSQL datastores only).

scripts run

Run pending escape hatch data scripts for a NoSQL datastore against a target environment. Lists the pending scripts (tracked by name and content hash in schema state), prompts for confirmation, executes them in version order with connection config injected as environment variables, and records each completion in schema state.

celerity schema scripts run userStore --env production
celerity schema scripts run userStore --env production --mark-only

The first positional argument is the name of the celerity/datastore resource in the blueprint.

See Escape Hatch Data Scripts for the script format and execution model.

--env

Environment Variable: CELERITY_CLI_SCHEMA_SCRIPTS_RUN_ENV

Configuration Key: schemaScriptsRunEnv

Type: string

The target environment to run scripts against. Required.

--mark-only

Type: boolean

Default Value: false

Record pending scripts as complete in schema state without executing them. Use for scripts that were run out-of-band (e.g. through a batch processing system).

validate

Validate schema files, blueprint references and contracts for both SQL databases and NoSQL datastores:

• Schema YAML files parse correctly
• SQL databases: Foreign keys reference valid tables and columns; migration SQL files parse as valid SQL for the target engine; the migration directory is consistent with its integrity file (atlas.sum)
• NoSQL datastores: Field types are valid (string, number, boolean, object, array); nested fields/items match their parent type; required fields exist in the fields map; blueprint keys, indexes and timeToLive fields exist in the schema with scalar types (key fields must be in shared fields and required); entity definitions reference a valid discriminator field
• Handlers linked to a celerity/sqlDatabase or celerity/datastore have the resource in their label scope
• Schema contracts are evaluated against pending changes — exits with a non-zero exit code if any blocking contracts are affected, prints warnings for notify contracts (if a schema-contracts.yaml file exists and deployed state is available)
• Generated types are up-to-date with the schema (when --check-codegen is set)

celerity schema validate

--check-codegen

Type: boolean

Default Value: false

Check that generated type files are up-to-date with the current schema. If generated types are stale, validation will fail.

export

Export the schema in different formats for documentation, pipeline integration or visualisation.

celerity schema export --format sql
celerity schema export --format markdown
celerity schema export --format json-schema
celerity schema export --format mermaid

--format

Type: string

Allowed Values: sql | markdown | json-schema | mermaid | avro

The output format for the schema export.

--out

Type: string

The output file path. If not specified, output is written to stdout.

codegen

Generate type-safe code from schema definitions. For SQL databases, produces types representing table rows and column name constants. For NoSQL datastores, produces item types with optional (?) and nullable (| null) semantics reflecting the required list and nullable flags in the schema.

celerity schema codegen --lang typescript --out ./src/generated/
celerity schema codegen --lang python --out ./src/generated/

--lang

Type: string

Allowed Values: typescript | python | go | java | csharp

The target language for code generation. Go, Java and C# support is planned for v1.

--out

Type: string

The output directory for generated files. Required.

show

Show the currently deployed schema for a database or datastore resource in a given environment. Reads from the deployed schema state.

celerity schema show ordersDb --env production
celerity schema show userStore --env production

The first positional argument is the name of the celerity/sqlDatabase or celerity/datastore resource in the blueprint.

--env

Environment Variable: CELERITY_CLI_SCHEMA_SHOW_ENV

Configuration Key: schemaShowEnv

Type: string

The target environment to show the schema for. Required.

history

Show the change history for a database or datastore resource in a given environment. Displays what changed, when, and which schema updates were applied.

celerity schema history ordersDb --env production
celerity schema history userStore --env production

The first positional argument is the name of the celerity/sqlDatabase or celerity/datastore resource in the blueprint.

--env

Environment Variable: CELERITY_CLI_SCHEMA_HISTORY_ENV

Configuration Key: schemaHistoryEnv

Type: string

The target environment to show history for. Required.

version

Prints the version of the Celerity CLI.

celerity version