Skip to main content
Both SDKs ship the same kardinal command, with the same subcommands, output, and exit codes. It covers every operation of the API, plus a few diagnostics:
Run kardinal --help, or --help after any subcommand, for its arguments and options.

​
Installing the command-line tool

Either one works, whatever language your project uses: pick the runtime you already have. See Installing the command-line tool for an installation inside a project.

​
Authentication

The command reads the same KARDINAL_API_KEY and KARDINAL_BASE_URL environment variables as the SDK clients. It has no --api-key option, so a key never lands in your shell history or in the process list.

​
Diagnostics

kardinal auth check is the first thing to run when nothing else works. It makes one read-only call to the API, creating nothing and consuming no credits, and reports whether the key is accepted, the host it was checked against, and the agency (sandbox or production) it belongs to. kardinal version prints the package version and the API version it targets: include it when you report an issue.

​
Local validation

validate checks a JSON plan file on your machine, with no API call and no credits: required fields, types, and misspelled keys, each reported with its path in the plan. It exits with code 0 when the plan is valid and 1 otherwise. It’s the same check submit runs before sending — see Validating locally before you spend credits. To accept a field the API supports but your SDK version doesn’t know yet, name it with --allow-unknown, once per field. The option also exists on plans submit and plans update.

​
Output and exit codes

  • Output: a readable table in a terminal; JSON when the output is piped or redirected, or with --json.
  • Errors: always JSON, whatever the output mode, since an error is what a calling script most needs to parse.
  • Exit codes: 0 success, 1 business error (refused plan, limit hit, plan not found…), 2 usage error (wrong arguments).
kardinal routing solutions wait <id> accepts --timeout <seconds>, and reports how the optimization ended in its finalState field.

​
Scripting in CI

A CI job can validate every plan file before anything reaches the API:
To submit from a pipeline, store the key as a masked CI secret exposed as KARDINAL_API_KEY, and read the JSON output with a tool such as jq:
Use a sandbox key for pipelines that run on every commit: it consumes no credits.

​
Project setup for AI coding assistants

init writes .kardinal/SKILL.md in the current folder: a short file that tells an AI coding assistant working in the project that the SDK is available, with a three-line example of its use. Commit it with the project. kardinal routing demo submits the example plan and waits for its solution: a quick end-to-end check of a new setup. It creates a real plan: with a production key, it consumes credits.