CLI reference

This page is generated by hand from cli/cli_registry.c and cli/cli_options.c — the same source polycall --help reads, so it cannot silently drift from the accepted command set (CLI-004/ CLI-019). Run polycall --help or polycall <command> --help for the live version.

Invocation shape

polycall [command] [subcommand] [-shorthand] [--flags] [Polycallfile]

polycall, polycall --help/-h, and polycall --version are the only bootstrap exceptions — they print and exit without a command/subcommand. Every other invocation needs a registered command and subcommand. At most one trailing positional argument is accepted: a path whose final filename selects the Polycallfile (default ./Polycallfile when omitted for commands that need one).

--json/-j is a flag on a command, not a command by itself — write polycall config validate --json, never polycall --json.

--file/-f is a plain alias for that same trailing path — polycall runtime start -f Polycallfile and polycall runtime start Polycallfile do exactly the same thing. It is not a second, independent way to select configuration: supplying a path both positionally and via -f (or via -f twice) is the same "multiple configuration paths given" error as supplying it twice positionally, and the option placement rule below applies to it too.

Option placement

Options must appear before the Polycallfile path, not after:

polycall runtime stop --json ./Polycallfile     # correct
polycall runtime stop ./Polycallfile --json     # rejected: usage error, exit 2

This is deliberate (CLI-007): once a bare (non-flag) token is consumed as the configuration path, every following token is rejected rather than guessed at.

Command registry

Command Subcommand Config Effect
config validate required Parse and validate without activation
config show required Display redacted effective configuration
config migrate destination required Convert explicitly named legacy inputs — registered, reports unsupported
runtime start required Run foreground runtime
runtime status required Query authenticated runtime state — reports unavailable, exit 7
runtime stop required Request bounded graceful shutdown
runtime reload required Submit candidate configuration for validation — reports unsupported
call invoke required Execute one typed invocation
service list required List authorized visible service registrations — reports unavailable, exit 7
service inspect required Inspect visible methods and capability state — reports unavailable, exit 7
telemetry snapshot required Obtain bounded metric snapshot — reports unavailable, exit 7
doctor check required Diagnose configuration and runtime prerequisites
version show not required Report product, ABI, protocol, and schema versions

Rows marked reports unavailable/unsupported are real, honest responses, not stubs pretending to work: service.*/telemetry snapshot/runtime status/runtime reload need Phase F's management protocol against an already-running, separately-addressed runtime, which does not exist yet; config migrate needs a historical-format reader that hasn't been written. Nothing here fabricates a success.

There used to be a binding list/binding check command pair. It was removed: LPV1-07's language set is a schema-level enumeration (service.*.language), not something the runtime tracks build/package support for, so a command reporting "support state" for it was reporting information the runtime doesn't actually have.

Global options

Long Short Meaning
--help -h Command help; valid even with other required options missing
--json -j Structured single-object JSON result instead of human text
--quiet -q Suppress progress/diagnostic lines on stderr; never suppresses the result
--verbose -v More diagnostic detail on stderr; mutually exclusive with --quiet
--timeout-ms -t Positive per-operation wait bound (tightens, never loosens, the configured maximum)
--file -f Alias for the trailing Polycallfile path

Command-specific options

Long Short Used by
--service -s call invoke, service inspect
--method -m call invoke
--input -i call invoke — a JSON request file, or - for stdin
--from none config migrate, repeatable
--overwrite none config migrate

Parsing rules

  • --service math and --service=math are both accepted.
  • A short option's value must be the next token (-s math); an attached value (-smath) is rejected, as is bundling (-qvj).
  • Boolean flags never take a value — --json=true is a usage error.
  • A nonrepeatable option given twice is a usage error, even with matching values.
  • All options are case-sensitive.

Exit codes

Code Meaning
0 Success
1 Unclassified operational failure
2 Invalid command syntax or option usage
3 Missing, invalid, or unsupported configuration
4 Authentication or authorization denied
5 Requested service, method, or resource not found
6 Timeout or deadline exceeded
7 Runtime or transport unavailable
8 Requested feature unsupported
9 Resource exhausted or operation busy
10 Internal invariant or implementation failure
130 Interrupted (e.g. Ctrl+C during runtime start)

JSON output shape

A finite command's --json output is one object:

{"ok": true, "command": "...", "subcommand": "...", "status": "...", "data": { }, "error": null}

error is null on success; on failure it is {"code": "...", "message": "..."} and data is null unless the command explicitly defines partial diagnostic data (call invoke's overflow rejection is one such case — see Your first Python call). runtime start --json is the one exception: it is long-running, so it emits a newline-delimited stream of independently parseable JSON event objects instead of a single result.