> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kardinal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Command-line tool

> Use the kardinal command shipped with both SDKs to check your API key, validate plan files for free, script calls in CI, and set up projects for AI assistants.

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:

```
kardinal auth check                    confirms the API key works, and shows its host and agency
kardinal version

kardinal routing plans submit <file> | get <id> | update <file> | delete <id>
kardinal routing plans list | start <id> | stop <id> | status <id>
kardinal routing plans validate <file> local only, no API call, no credits
kardinal routing solutions get <id> | objectives <id> | wait <id>

kardinal routing demo                  submits the example plan, waits for it
kardinal init                          writes .kardinal/SKILL.md, a pointer to the SDK for AI coding assistants
```

Run `kardinal --help`, or `--help` after any subcommand, for its arguments and options.

## Installing the command-line tool

<CodeGroup>
  ```bash Python theme={null}
  pipx install "kardinal-ai[cli]"
  ```

  ```bash TypeScript theme={null}
  npm install -g @kardinal-ai/sdk commander
  ```
</CodeGroup>

Either one works, whatever language your project uses: pick the runtime you already have. See [Installing the command-line tool](/sdks/installation#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.

```bash theme={null}
export KARDINAL_API_KEY="<your API key>"
kardinal auth check
```

## 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

```bash theme={null}
kardinal routing plans validate plan.json
```

`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](/sdks/building-plans#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:

```bash theme={null}
for f in plans/*.json; do
  kardinal routing plans validate "$f" || exit 1
done
```

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`:

```bash theme={null}
plan_id=$(kardinal routing plans submit plan.json | jq -r '.id')
kardinal routing solutions wait "$plan_id" --timeout 900
```

Use a sandbox key for pipelines that run on every commit: it consumes no credits.

## Project setup for AI coding assistants

```bash theme={null}
kardinal init
```

`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](/sdks/quickstart) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.