CLI Overview

chant provides a CLI for building, linting, and managing infrastructure definitions.

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
`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
`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 — project users don’t typically need them.

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 is built in and needs nothing installed; --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

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

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 automatically discovers infrastructure files based on these rules:

Included:

All .ts files in the specified directory and subdirectories

Excluded:

Files in node_modules/ directories
Test files: *.test.ts, *.spec.ts
TypeScript declaration files: *.d.ts

Error Handling

The CLI provides structured error output for different types of errors:

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`

Display help information for the CLI.

chant --help