CLI reference

callagent v0.1.0, generated from the command manifest the binary is built from — so every flag documented here is a flag the binary accepts.

Installing

WARNING

@callagent/cli is private: true with no publishConfig, so it is not on npm — npm i -g @callagent/cli and npx @callagent/cli both fail with a 404. Until it is published, the binary is built and run from a checkout. Everything below describes that binary; it is callagent once the package is published and installed.

pnpm install
pnpm --filter @callagent/cli build
node apps/cli/dist/index.js --help

Commands

Command	Purpose	Status
init	Scaffold a config-as-code project.	implemented
validate	Schema-check local files and report file/line errors.	implemented
plan	Diff local configuration against the remote organization.	implemented
apply	Apply the plan to the remote organization.	implemented
export	Pull the live configuration down into files.	implemented
listen	Forward webhooks to a local URL and pretty-print them (§111).	implemented
login	Store an API key in the OS keychain.	implemented
logout	Remove stored credentials.	implemented
whoami	Show the authenticated organization and where the key is stored.	implemented

Configuration as code

init

callagent init [directory] [options]

Creates callagent.yaml with DEV/UAT/PROD environments, the resource directories from §110 (assistants/, tools/, squads/, knowledge/, policies/), a sample assistant and tool, and a .gitignore that keeps .callagent/ state out of commits.

It never overwrites an existing file unless --force is passed.

Arguments

Argument	Required	Description
directory	—	Where to create the project. Defaults to the current directory.

Options

Flag	Default	Description
--api-url <url>	http://localhost:8000	API URL for the DEV environment.
--force		Overwrite files that already exist.
--no-samples		Skip the sample assistant and tool.

Examples

# Scaffold in the current directory.
callagent init

# Scaffold into a new directory pointing at production.
callagent init voice-config --api-url https://api.callagent.dev

validate

callagent validate [options]

Parses every file under the resource directories and validates it against the @callagent/contracts schemas. Errors carry the file, line, column and field, so they are actionable without opening the schema.

Also catches problems the schema cannot see: duplicate resource names, tools an assistant references that do not exist, and unresolved ${variable} references.

Exits 2 when anything is invalid, so it works as a CI gate.

Options

Flag	Default	Description
-e, --env <name>		Environment from callagent.yaml (DEV/UAT/PROD). Defaults to defaultEnvironment, overridable with CALLAGENT_ENV.
-k, --kind <kind...>		Limit to one or more resource kinds: assistants, tools, squads, knowledge, policies.
--json		Emit machine-readable issues instead of text.

Examples

# Validate everything for the default environment.
callagent validate

# Validate with PROD variables and emit JSON for CI.
callagent validate --env prod --json

plan

callagent plan [options]

Fetches the current state of every syncable resource and prints a field-level create/update/delete plan — the actual before and after of each changed field, not just "assistant changed".

Local files are matched to remote records by explicit id, then by the id recorded in .callagent/state.<env>.json, then by name. Fields a file omits are left alone: config-as-code files are partial, and the server owns what they do not mention.

--prune additionally proposes deleting resources this project created and no longer declares; resources created in the dashboard are never proposed for deletion.

Options

Flag	Default	Description
-e, --env <name>		Environment from callagent.yaml (DEV/UAT/PROD). Defaults to defaultEnvironment, overridable with CALLAGENT_ENV.
-k, --kind <kind...>		Limit to one or more resource kinds: assistants, tools, squads, knowledge, policies.
--prune		Propose deleting managed resources that are no longer declared locally.
--json		Emit the plan as JSON.
--detailed-exitcode		Exit 2 when there are changes, 0 when there are none (for CI).
--out <file>		Write the plan to a file that apply --plan can consume.

Examples

# Show what applying to UAT would change.
callagent plan --env uat

# Fail a CI job when configuration has drifted.
callagent plan --detailed-exitcode

apply

callagent apply [options]

Computes a plan, shows it, asks for confirmation, then executes it. Individual failures do not stop the run: every item is attempted and the report lists exactly what applied and what did not, so re-running finishes the job.

Applying twice in a row changes nothing the second time — ids are recorded in .callagent/state.<env>.json and unchanged fields produce no request at all.

Environments marked protected: true in callagent.yaml refuse --auto-approve unless --force is also given.

Options

Flag	Default	Description
-e, --env <name>		Environment from callagent.yaml (DEV/UAT/PROD). Defaults to defaultEnvironment, overridable with CALLAGENT_ENV.
-k, --kind <kind...>		Limit to one or more resource kinds: assistants, tools, squads, knowledge, policies.
--auto-approve		Skip the confirmation prompt.
--force		Allow --auto-approve on a protected environment.
--prune		Also delete managed resources no longer declared locally.
--plan <file>		Apply a plan previously written by plan --out.
--json		Emit the result as JSON.

Examples

# Interactive apply to DEV.
callagent apply --env dev

# Non-interactive apply in a deploy pipeline.
callagent apply --env prod --auto-approve --force

export

callagent export [options]

Writes every syncable resource in the organization to YAML under the project directories, so a customer who built everything in the dashboard can adopt config-as-code without retyping it.

Server-managed fields (ids, timestamps, version counters) are stripped, and the id map is recorded in .callagent/state.<env>.json so the next plan matches the exported files to the records they came from and reports no changes.

Options

Flag	Default	Description
-e, --env <name>		Environment from callagent.yaml (DEV/UAT/PROD). Defaults to defaultEnvironment, overridable with CALLAGENT_ENV.
-k, --kind <kind...>		Limit to one or more resource kinds: assistants, tools, squads, knowledge, policies.
-o, --out <dir>		Write to this directory instead of the project root.
--force		Overwrite files that already exist.
--keep-ids		Keep the remote id field in the exported files.

Examples

# Pull everything into the current project.
callagent export

# Export just the assistants somewhere else.
callagent export --kind assistants --out ./snapshot

Development

listen

callagent listen [options]

TIP

Registration targets POST /api/v1/webhooks. Against a control plane that does not publish it, listen prints the URL to paste into the dashboard and accepts --secret instead of failing.

Starts a public tunnel (Cloudflare Tunnel, or ngrok if that is what you have), registers the resulting URL as a webhook endpoint on the organization, picks up the signing secret returned by that call, then prints every event it receives with its HMAC signature verified — and forwards it to your local app.

The endpoint is deleted on exit unless --keep is passed.

If neither cloudflared nor ngrok is installed, it prints the exact install and run commands rather than pretending to have started something. --url skips the tunnel entirely when you already have a public URL.

The endpoint it registers is removed on exit unless --keep is passed.

Options

Flag	Default	Description
-e, --env <name>		Environment from callagent.yaml (DEV/UAT/PROD). Defaults to defaultEnvironment, overridable with CALLAGENT_ENV.
-f, --forward-to <url>	http://localhost:8080/webhooks/callagent	Local URL to forward events to.
-p, --port <port>	4040	Port the local receiver listens on.
--url <url>		Use this public URL instead of starting a tunnel.
--tunnel <provider>	auto	cloudflared
--events <event...>		Only subscribe to these event types.
--secret <secret>		Signing secret to verify with. Only needed when the endpoint was created elsewhere.
--keep		Leave the webhook endpoint registered after exit.
--print-body		Print the full JSON body of each event.

Examples

# Tunnel production webhooks to a local dev server.
callagent listen --forward-to http://localhost:3000/hooks

# Use an existing tunnel and filter to one event.
callagent listen --url https://my.ngrok.app --events call.ended

Authentication

login

callagent login [options]

Reads a private API key from stdin or an interactive prompt — never from an argument, so it does not land in shell history or ps — verifies it against the API, and stores it in the OS keychain (macOS Keychain, libsecret on Linux).

Where no keychain is available it falls back to ~/.callagent/credentials.json, created mode 0600 inside a 0700 directory. CALLAGENT_API_KEY in the environment always wins and is what CI should use.

Options

Flag	Default	Description
-e, --env <name>		Environment from callagent.yaml (DEV/UAT/PROD). Defaults to defaultEnvironment, overridable with CALLAGENT_ENV.
--api-url <url>		Override the environment API URL for this login.
--stdin		Read the key from stdin instead of prompting.

Examples

# Prompt for a PROD key and store it in the keychain.
callagent login --env prod

# Non-interactive login.
echo "$KEY" | callagent login --stdin

logout

callagent logout [options]

Deletes the stored key for an environment from the keychain and the credentials file.

Options

Flag	Default	Description
-e, --env <name>		Environment from callagent.yaml (DEV/UAT/PROD). Defaults to defaultEnvironment, overridable with CALLAGENT_ENV.
--all		Remove credentials for every environment.

Examples

# Forget the PROD key.
callagent logout --env prod

whoami

callagent whoami [options]

Calls the API with the stored credential and prints the organization, the API URL, which storage backend holds the key, and the file permissions when it is on disk.

Options

Flag	Default	Description
-e, --env <name>		Environment from callagent.yaml (DEV/UAT/PROD). Defaults to defaultEnvironment, overridable with CALLAGENT_ENV.
--json		Emit JSON.

Examples

# Confirm which organization you are pointed at.
callagent whoami

Exit codes

Code	Meaning
0	Success. Also apply when you decline the confirmation prompt.
1	An error you can fix: a failed apply, a protected environment, a missing tunnel binary.
2	validate found problems, or plan --detailed-exitcode found changes.
3	Not authenticated, no stored credentials, or the API answered 401/403.