chant import

Synopsis

chant import <template-file> [flags]
chant import --from <env> [flags]
chant import --kustomize <dir> [flags]
chant import --agents [flags]

Description

chant import reads an existing infrastructure template (e.g. a CloudFormation JSON template), detects which lexicon handles it, and generates TypeScript resource definitions. This lets you adopt chant incrementally by importing your current infrastructure rather than rewriting it from scratch.

With --from <env> it reads the live cloud/cluster instead of a file: it resolves the environment, calls each project lexicon’s exportResources() for full-fidelity config, and generates TypeScript from that. This is the cloud->code direction — the way to adopt an orphaned resource back into source.

With --kustomize <dir> it renders a kustomization first and imports the rendered manifests through the k8s lexicon. It runs kustomize build <dir>, falling back to kubectl kustomize <dir> when the standalone binary is absent. The flag names the lexicon, so no template detection happens. A rendering error exits nonzero with the first line of the tool’s message.

The import process:

1. Reads and parses the template file (JSON)
2. Asks each lexicon plugin if it recognizes the template via detectTemplate()
3. Uses the matching lexicon’s templateParser() to extract resources into an intermediate representation
4. Uses the lexicon’s templateGenerator() to produce TypeScript files
5. Organizes generated files by resource category (storage, compute, network, other)

Flags

Flag	Description
--from <env>	Import from a live environment instead of a template file
--kustomize <dir>	Render the kustomization at dir and import the output as Kubernetes manifests. Needs kustomize or kubectl on the path
-d, --lexicon <name>	With --from, restrict to one lexicon (e.g. aws, k8s)
--type <ResourceType>	With --from, export only resources of this type
--name <name>	With --from, export only the resource with this name
--owned	With --from, restrict to chant-owned resources — those carrying the live ownership marker
--verbatim	With --from, keep server-defaulted fields instead of stripping to declared shape
-o, --output <dir>	Output directory (default: ./infra/)
--force	Overwrite existing files
--agents	Import this machine’s agent configuration instead of a template file (see below)
--scope <list>	--agents only: comma-separated system, user, project (default: all)
--runtime <list>	--agents only: comma-separated claude, codex, gemini, opencode, cursor (default: all)
--all-projects	--agents only: import every project registered in ~/.claude.json, not just the path argument

Caution

Live import may emit sensitive values (keys, tokens, passwords) into generated source — unlike chant lifecycle observation, which only reads scrubbed metadata. The command prints a warning; review generated files before committing.

--agents is the exception: it rewrites literal credentials to ${VAR} references rather than copying them, and reports which sites it redacted. Review the output anyway.

Importing agent configuration (--agents)

chant import --agents is the other half of chant audit --agents: where the audit reports on the agent configuration found on a machine, this re-expresses it as chant code, so a setup that accumulated by hand over months becomes reviewable, version controlled, and reproducible.

chant import --agents                                  # → ./infra/agents/
chant import --agents --scope user -o infra/agents/    # just the home directory

The default target is the fountain lexicon, whose Agent models the same four ideas the harnesses do:

local agent config	fountain
CLAUDE.md / AGENTS.md	Agent.system
mcpServers / mcp_servers	Agent.mcp_servers
skills/*/SKILL.md	Agent.skills
settings env	Environment.env_vars

Three places where it deliberately does not transcribe:

• Secrets are not carried over. A literal credential found in local config is rewritten to a ${VAR} reference. Generated code gets committed; transcribing a live secret into it would turn a local mistake into a repository one. This includes bearer tokens in MCP headers, not just env.
• Egress is derived, not copied. A local agent has the machine’s full network access; a fountain sandbox must declare intent. The hosts the config’s own remote MCP servers use become the allowed_hosts allowlist, and everything else is denied.
• Local skills are inlined by content. A skill that exists only on this machine has no upstream to install from, so its text is embedded — that is what lets the generated code reproduce the setup somewhere else.

The command reports every lossy step: a site it could not map (Cursor has no fountain runtime value), a model it had to default because the local config pinned none, and any site where a credential was redacted.

A lexicon opts into being an --agents target by implementing agentConfigImporter() — see lexicon authoring.

Usage

# Import a template file
chant import template.json

# Import to a specific directory
chant import template.json --output src/

# Import live infrastructure from an environment
chant import --from prod

# Adopt a single orphaned resource back into source
chant import --from prod --name my-bucket --output src/

# Keep server-defaulted fields
chant import --from prod --verbatim

# Render an overlay and import what it produces
chant import --kustomize ./k8s/overlays/prod --output src/

Exit Codes

Code	Meaning
0	Import completed successfully
1	Error (unrecognized template format, parse error, or write failure)

See Also

• Importing Templates — user guide
• Lexicon Authoring — implementing detectTemplate() and templateParser()