CLI reference¶

This page tracks docs/CLI.md in the repository, which is generated by hand from the same command registry (src/cli/cli_commands.c) that polycall --help reads — run polycall help or polycall help <command> for the live version, which cannot drift from the accepted command set.

Invocation shape¶

polycall [global-options] <command> [subcommand] [arguments]

No arguments prints root help on stdout and exits 0 — non-interactive input never starts a REPL; polycall repl is the only way into the interactive session. --version/-V prints one line and exits without touching runtime init, the network, or any configuration file. --help/-h prints help for the resolved command and exits 0.

An unknown option, unknown command, unknown subcommand, a repeated scalar option, a missing option value, or a trailing argument that cannot be placed is a usage error (exit 2). -- ends option parsing; every following token is positional and argv is never re-tokenised, so a quoted path with spaces survives intact.

Commands¶

Command	Behaviour
help [command [subcommand]]	deterministic help text; no side effects
version	same as --version
doctor	read-only build/platform/ABI/core-capability report; never starts a service or evaluates a provider
config validate --provider c:LIB\|node:MOD\|python:MOD	run the provider, validate through the typed model
config validate --envelope FILE	validate a pre-generated canonical envelope
config validate [path]	no selector → legacy Polycallfile/Polycallrc loader
config show <selector> [--provenance]	print the canonical envelope + winning source per field
config load [language]	report the legacy load order
config migrate <src> <Polycallrc.lang>	copy-migrate a legacy file, refuses to overwrite
config migrate --from-legacy [--language L] --output F	legacy effective model → v2 envelope; reports unmapped keys
telemetry emit --event NAME [--service S] [--operation OP] [--status ST] [--detail TEXT] [--correlation-id GUID]	append one GUID + timestamp correlated event to the sink
telemetry show [--limit N]	print the most recent recorded events (default 20)
telemetry status	whether telemetry is enabled and where it writes
repl	explicit interactive session over this same command registry
start --endpoint host:port [--auth-token T] [--endpoint-file F] [--load PATH ...] [--daemon]	foreground runtime; port 0 = ephemeral; --load (repeatable) adds operations from a plugin shared library before binding; --daemon detaches into the background and returns immediately, printing the detached process's PID
status --endpoint host:port	describe registered operations over the control channel
stop --endpoint host:port [--auth-token T]	authenticated shutdown
call SERVICE OPERATION --endpoint host:port [--input F\|- \| --input-value JSON]	one round trip, no retry

Global options¶

Option	Meaning
--project-root PATH	project root for resolving relative paths
--config PATH	explicit configuration file / provider
--language LANG	language layer / adapter to select
--format text\|json	output format for finite commands (default text)
--no-color	disable ANSI colour
--quiet	suppress non-essential text on stderr
--timeout-ms N	deadline (non-negative integer) for commands that support one
-h, --help	show help and exit
-V, --version	show version and exit

Globals are accepted before or after the command tokens, but never after --. --opt=value and --opt value are both accepted for scalar options.

--format json¶

A finite command with --format json prints exactly one UTF-8 JSON object on stdout, for success and failure alike:

{"schema_version":1,"ok":true,"command":"doctor","data":{...},"error":null}

On failure ok is false, data is null, and error is {"code","message","hint"} with a stable code. Diagnostics/logs go to stderr.

Exit codes¶

Code	Meaning
0	completed successfully
1	runtime / internal failure
2	CLI usage error
3	invalid or missing selected configuration
4	missing dependency, adapter, or unsupported capability
5	transport / endpoint unavailable
6	operation deadline exceeded
7	authentication / authorization rejected
130	user interruption (SIGINT)

Library status values are mapped onto these centrally in the CLI; raw enum values are never used as the shell contract.

Telemetry¶

Every start bind/stop and every call round trip appends one JSONL event to <project-root>/.polycall/telemetry.jsonl (override with POLYCALL_TELEMETRY_LOG, disable with POLYCALL_TELEMETRY=off) — a random RFC 4122 v4 GUID correlation_id, a millisecond UTC timestamp, and (for paired call.start/call.end events) a monotonic-clock duration_ns. See docs/CLI.md for the exact schema.