kardinal command, with the same subcommands, output, and exit codes. It covers every operation of the API, plus a few diagnostics:
kardinal --help, or --help after any subcommand, for its arguments and options.
Installing the command-line tool
Authentication
The command reads the sameKARDINAL_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:
0success,1business error (refused plan, limit hit, plan not found…),2usage 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:KARDINAL_API_KEY, and read the JSON output with a tool such as jq:
Project setup for AI coding assistants
init writes a skill in the current folder: .claude/skills/kardinal-python/SKILL.md with the Python SDK, .claude/skills/kardinal-typescript/SKILL.md with the TypeScript SDK. Each SDK writes its own skill folder, so both can live in one repository. From Python 2.2.0 and TypeScript 1.3.0, init writes the same file a second time, under .agents/skills/ instead of .claude/skills/. Claude Code loads the skill from .claude/skills/. OpenAI Codex and Mistral Vibe load it from .agents/skills/. It tells the assistant when to load it, gives an example of the SDK in use, lists the pitfalls of an integration (the sandbox’s 5-second cap on the optimization, a bounded wait, and how to read a solution), and links to these docs. Run it at the root of your repository, and commit the file with the project. In a running Claude Code session, run /reload-skills to load it.
Running init again overwrites both files. The old .kardinal/SKILL.md is no longer written, and you can delete it.
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.
