Celerity

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

Note

CLI options take precedence over configuration from environment variables and values from a configuration file.

`--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-changes, 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: app.blueprint.yaml

`--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.

Note

The "app deploy config" file provides a convenient way to set up the deploy configuration specifically for a Celerity application. All configuration in the deployTarget section of the app deploy config file will be used to generate the final configuration organised by the underlying provider and transformer plugins.

This means that when --check-deploy-config is set, the CLI will validate the configuration in the deployTarget section of the app deploy config file.

`stage-changes`

`deploy`

`destroy`

`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.

`--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.

`test`

Run tests for a Celerity application. This will set up an isolated environment that sets up and tears down test fixtures for local development. The underlying test runner will depend on the language used for the application.

`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 the migration plan and contract impact for pending schema changes without applying them. This compares the schema YAML (desired state) against the current deployed state and generates the changes that would be applied.

The output includes:

SQL databases: Auto-generated DDL statements from the schema diff, pending escape hatch SQL scripts
NoSQL datastores: Field-level changes (added, removed, type changed), pending escape hatch data scripts. No DDL is generated — field changes are application-layer only.
Contract impact analysis (which contracts would be satisfied or broken)
Warnings for ambiguous or destructive changes

celerity schema diff

`--env`

Environment Variable: CELERITY_CLI_SCHEMA_ENV

Configuration Key: schemaEnv

Type: string

The target environment to diff against. When specified, the current state is read from the deployed schema state for that environment.

`apply`

Apply schema changes outside of a full deployment.

SQL databases: Executes the auto-generated DDL and escape hatch SQL scripts against the target database.
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.

`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; escape hatch SQL files parse as valid SQL for the target engine
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
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.

Format	SQL Databases	NoSQL Datastores	Description
`sql`	✅	—	SQL CREATE TABLE statements (DDL)
`markdown`	✅	✅	Human-readable documentation with table/field descriptions and metadata
`json-schema`	✅	✅	Machine-readable JSON Schema for pipeline tool integration
`mermaid`	✅	—	Entity-relationship diagram in Mermaid syntax
`avro`	—	✅	Apache Avro schema for data pipeline integration

`--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.

Language	Output	Status
`typescript`	Interfaces, column constants, table name constants	✅ Available in v0
`python`	TypedDict classes	✅ Available in v0
`go`	Struct types	🚀 Planned for v1
`java`	Record classes	🚀 Planned for v1
`csharp`	Record types	🚀 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.

Reference

Global Options

`--config`

`--app-deploy-config-file`

`--connect-protocol`

`--engine-endpoint`

`help`

`validate`

`--blueprint-file`

`--check-blueprint-vars`

`--check-plugin-config`

`stage-changes`

`deploy`

`destroy`

`init`

`--language`

`dev`

`run`

`test`

`schema`

`diff`

`--env`

`apply`

`--env`

`--auto-approve`

`validate`

`--check-codegen`

`export`

`--format`

`--out`

`codegen`

`--lang`

`--out`

`show`

`--env`

`history`

`--env`

`version`

On this page