chant run

Synopsis

chant run <name> [flags]
chant run list [flags]
chant run status <name> [flags]
chant run signal <name> <signal> [flags]
chant run cancel <name> [flags]
chant run log <name> [flags]
chant run --components <name|all> [flags]

Description

chant run starts and manages Op workflows — named, phased workflows defined in *.op.ts files — and, with --components, component deploy compositions.

chant run <name> runs local by default: the Op executes in-process with no Temporal server, worker, or built worker.ts. Pass --temporal to run against a Temporal cluster instead (worker spawn + workflow submission). One flag selects the runtime — no config is inspected. See Local vs Temporal for the trade-off.

Local mode covers phase sequencing, retries, activity profiles, and onFailure compensation. Gates, schedules, durable resume, and the run-management subcommands (list / status / log / signal / cancel) require --temporal and a reachable Temporal server. Connection settings come from chant.config.ts under temporal.profiles; see Worker Profiles.

Subcommands

run <name>

Run an Op. Local by default — executes in-process, rendering each phase and step as it runs. With --temporal, spawns the compiled worker and submits the workflow to Temporal, polling status every 3 seconds until it completes or fails.

chant run alb-deploy              # local executor (default)
chant run alb-deploy --json       # structured result on stdout
chant run alb-deploy --temporal             # run via Temporal
chant run alb-deploy --temporal --profile cloud
chant run alb-deploy --temporal --report    # print deployment report instead of running

A gate or schedule in the Op fails fast in local mode with an actionable message — re-run with --temporal.

run list

List all discovered Ops (*.op.ts files) with their current Temporal run status. Requires --temporal.

chant run list

Output columns: NAME, PHASES, TASK-QUEUE, DEPENDS, OVERVIEW, STATUS.

run status <name>

Show the current state of an Op’s latest workflow run.

chant run status alb-deploy

run signal <name> <signal>

Send a named signal to unblock a gate step in a running workflow.

chant run signal alb-deploy gate-dns-delegation

The signal name must match the signalName passed to the gate() builder in the Op definition. Pass --components to signal a component’s durable gate instead (see run --components below).

run cancel <name>

Cancel the active workflow run. Requires --force.

chant run cancel alb-deploy --force

Pass --components to cancel a component’s durable workflow instead.

run log <name>

Show run history for an Op.

chant run log alb-deploy

run --components <name|all>

Run a discovered component’s deploy composition. Local by default, on the same zero-dependency in-process executor as an Op — no Temporal server, worker, or build step needed. all runs every discovered component in dependency order (parallel-safe waves); a single name runs just that component.

chant run --components search-service --env staging
chant run --components all --env production

A gate anywhere in a local-mode component’s composition fails fast, before any step runs, with an actionable message pointing at --temporal.

On a successful run, chant run --components auto-emits one immutable release record per component that published a digest-bearing artifact — (component, env, digest, gitSha, runId, timestamp, actor), appended to the same release ledger the standalone chant components release command writes to. This is a post-run CLI step: it never runs inside the Temporal workflow (determinism), and it never runs at all when the deploy fails. See Auto-recorded releases below.

run --components <name> --temporal

Compiles the named component’s composition to a Temporal workflow (phases → workflow, capability steps → activities, gate → durable wait-for-signal, onFailure/rollback → saga compensation — mirroring Temporal::Op codegen), writes it to dist/components/<name>/, spawns the worker, and submits the workflow. Unlike local mode, a gate is fully supported here: the workflow durably waits for the signal, survivable across a worker crash.

chant run --components search-service --temporal
chant run signal search-service release-approval --components --temporal   # unblock a gate
chant run cancel search-service --force --components --temporal            # abort a run

Scoped to a single named component — chant run --components all --temporal is not supported (coordinating multiple durable workflows’ cross-component ordering is a separate concern from compiling one component’s composition).

The Temporal path auto-emits a release record the same way local mode does, read from the generated workflow’s own result (handle.result()) once it reports COMPLETED — the workflow itself never writes the ledger.

Auto-recorded releases

Auto-recording is on by default — no flag needed. It writes exactly one record per component whose deploy composition actually published a digest-bearing artifact (via publish-image, publish-artifact, or load-image-on-host); a component with no publish step, or a failed deploy, writes nothing. A ledger-write failure (e.g. a concurrent push, or no git remote configured) is reported as a warning and never turns an otherwise-successful deploy into a nonzero exit.

Opt out per-invocation with --no-release-record, or project-wide via chant.config.ts:

chant run --components search-service --env staging --no-release-record

chant.config.ts

export default {
  release: { autoRecord: false },
};

The --no-release-record flag always wins over config for that one invocation. See Observability for the release ledger this feeds, and chant components status to query it.

Flags

Flag	Description
--local	Run with the local in-process executor — the default (run <name>, run --components)
--temporal	Run via a Temporal cluster: gates, schedules, durable resume (run <name>, run --components <name>)
--components	Target a component instead of an Op (run --components, and run signal / run cancel against a component’s workflow)
--no-release-record	Skip auto-emitting a release-ledger record after a successful run --components deploy — default is ON (run --components)
--env <name>	Target environment, threaded into every capability’s context (run --components); defaults to local
--json	Emit the structured run result as JSON on stdout (run <name>, run --components)
-p, --profile <name>	Temporal worker profile to use (from chant.config.ts); implies Temporal mode
--report	Print a deployment report instead of running (run <name> --temporal only)
--force	Required for run cancel

Exit Codes

Code	Meaning
0	Success (workflow completed or command succeeded)
1	Error (workflow failed, Op not found, Temporal unreachable)

See Also

• Ops guide — define *.op.ts files
• Local vs Temporal — choose the runtime
• Worker Profiles — configure Temporal connection
• chant graph — visualize Op dependency graph