CLI Overview

llms.txt lists every page for an agent

The chant CLI builds and lints infrastructure definitions, runs Ops, and records deployed state.

Installation

The CLI is included in @intentius/chant. Install a lexicon package to get everything:

npm install --save-dev @intentius/chant-lexicon-aws

Usage

chant <command> [options] [path]

Commands

Command	Description
`init`	Scaffold a new chant project
`init lexicon`	Scaffold a new lexicon plugin project
`build`	Synthesize and write infrastructure output
`lint`	Lint intent definitions with semantic rules
`list`	List exported declarations in a project
`describe`	Show the effective, fully-resolved configuration for one component
`search`	Answer an estate question with a compact, edge-aware query
`query`	Run one read-only SQL statement over the snapshots, runs, gates, deploys and releases on chant/lifecycle
`import`	Import infrastructure templates and generate TypeScript
`audit`	Audit an existing repo’s CI/CD pipelines for security issues
`migrate`	Translate a workflow between lexicons (e.g. GitHub Actions → GitLab CI)
`carve advise`	Rank which Terraform resources are cheap to carve into native chant
`carve emit/bridge/apply`	Carve a resource out of Terraform, incrementally and reversibly
`vendor`	Pull reusable patterns into your repo, pinned and checksummed
`generate`	Generate typed code from CRDs and Helm charts your config declares
`update`	Sync lexicon type definitions
`doctor`	Check project health and configuration
`emulator`	Boot, stop, and inspect a lexicon’s local cloud emulator

Lexicon Development Commands

These commands are for lexicon authors.

Command	Description
`dev generate`	Generate lexicon artifacts (+ validate + coverage)
`dev publish`	Package lexicon for distribution
`dev onboard`	Onboard a new lexicon plugin
`dev check-lexicon`	Validate a lexicon bundle
`dev surface-diff`	Diff a regenerated lexicon’s API surface against its baseline

Op Commands

Run named, phased workflows defined in *.op.ts files. The local runtime runs in the chant process; --on <lexicon> hands the run to a configured lexicon that hosts one instead.

Command	Description
`run <name>`	Run an Op on the resolved runtime
`run list`	List all Ops with the run state the runtime reports
`run status <name>`	Show the latest run’s state
`run approve <op> <gate>`	Record a gate’s resolution, then wake the hosting runtime
`run cancel <name>`	Cancel the active run
`run log <name>`	Show run history for an Op
`graph`	Print the Op dependency graph

Workspace Commands

A chant.workspace.json makes a repository a workspace of members (Workspace Declaration). The records and lineage commands also work without one.

Command	Description
`workspace init`	Propose a declaration from the projects already in the repository, and write it on confirmation
`workspace ls`	List the declared members and example groups, with reason codes for members that can’t be read
`workspace status <env>`	Show each member’s latest release in an environment, and with `--compare-to <env>` which members differ from another
`workspace metrics`	The four DORA metrics per member and environment, from the deploy, release and revocation records
`workspace records --kind <file>`	Print the records a record kind locates, with reason codes for invalid ones
`workspace pin`	Print the integrity value that pins a plugin loaded by path
`workspace verify`	Check a change’s commits against the signers and roles read from its base revision
`workspace signers`	Show the signer history at base, and rotate the signer set with a threshold of the current signers
`workspace evidence`	Sign runner evidence over record hashes in a DSSE envelope, and verify it offline
`workspace lineage`	Show where a project’s files came from and which manual steps are open
`workspace upgrade [<scope>] --to <ref>`	Bring a scope to a newer template version, gated on the digest of the patch
`workspace check`	Fail on an unreadable lock, an open manual step or a failed declaration check (`WSP` ids, SARIF output)

State Commands

Capture and compare deployed infrastructure state. Snapshots are stored on an orphan git branch (chant/lifecycle); lifecycle diff --live queries the cloud directly for drift detection. AWS, fountain, K8s, GCP, and Azure surface their resources entity-keyed; Helm and Docker surface runtime artifacts. See chant lifecycle for the full surface.

Command	Description
`lifecycle snapshot <env>`	Query lexicon plugins, save resource + artifact metadata to orphan branch
`lifecycle show <env>`	Show latest lifecycle snapshot
`lifecycle diff <env>`	Compare current build against last snapshot (digest mode)
`lifecycle diff <env> --live`	Query cloud right now and report drift (seven categories: missing, orphan, disappeared, newly observed, drifted, unchanged, unobserved)
`lifecycle whoami <env>`	Who chant would act as in each configured lexicon, and what that principal is scoped to — read-only, before anything acts
`lifecycle log [env]`	History of lifecycle snapshots
`lifecycle gc`	Prune stored change sets, releases and run event files by the retention policy; a dry run without `--yes`
`lock <target>...`	Lock targets for a pull request on `chant/lifecycle`, so no other pull request applies or locks them until it merges or closes
`unlock --pr <n>`	Release the locks a pull request holds

Component Release Ledger + Status

Record immutable deploy events and reconcile them against live truth, joined by artifact digest. See chant components and Observability.

Command	Description
`components release <env>`	Append one immutable release record (`component`, digest, git sha, run id, actor) to the `chant/lifecycle` branch
`components status [env]`	What’s built vs. what’s deployed where, joined by digest (`--live` reconciles against live + ownership; `--compare-to <env>` cross-checks a digest across environments)

Server Commands

Command	Description
`serve lsp`	Start the LSP server for editor integration
`serve mcp`	Start MCP server for AI agent integration

Common Workflows

# Initialize and build a project
chant init my-infra --lexicon aws
cd my-infra
chant build

# Lint definitions
chant lint

# Import existing templates
chant import template.json

# Check project health
chant doctor

File Discovery

The CLI finds infrastructure files by these rules:

Included:

All .ts files in the specified directory and subdirectories

Excluded:

Files in node_modules/ directories
Anything in dot-directories and dist/ directories
Paths git ignores, nested .gitignore included
Child projects, when the directory being scanned is inside a project
Test files: *.test.ts, *.spec.ts
TypeScript declaration files: *.d.ts
Files that start with the “Generated by chant” marker chant writes into its own output
Files that carry the skip marker comment (see below)
Files named by the project’s exclude globs, unless an include glob names them too

An include glob also re-admits a directory these rules skip. Every command that walks the tree, chant audit included, does it the same way, so a directory one of them skips is skipped by all of them. See One walk for every command.

Keeping a script out of discovery

A runnable script that does its work at top level, such as an ops/run.ts that reads process.argv, would run during discovery, because discovery imports every file it finds. There are two ways to keep such a file out.

Put a comment line holding chant-discovery-skip within the first 1024 bytes of the file. A shebang line may come before it, and the rest of the line is free text:

#!/usr/bin/env -S node --import tsx
// chant-discovery-skip: runs an Op from the command line, declares nothing
const op = process.argv[2];

Or name the files in chant.config.ts, which suits a whole directory of scripts:

export default {
  lexicons: ["aws"],
  exclude: ["ops/**"],
};

Error Handling

The CLI reports errors in two groups:

Discovery Errors

Reported when files can’t be loaded or imported. Common causes: missing dependencies, syntax errors, invalid import paths, circular dependencies.

Build Errors

Reported during serialization. Common causes: circular dependencies between resources, invalid attribute references, missing required properties.

Global Options

`--verbose, -v`

Show stack traces on errors. For chant build, also list every resolved build parameter and every per-file fold decision instead of the one-line summaries.

`--help, -h`

Print help for the CLI.

chant --help

`--version, -V`

Print the installed chant’s version and exit. It is the version the MCP server reports as serverInfo.version.

chant --version