# The Katonic CLI

What the katonic-admin command-line tool does on the current build, which is air-gap bundle work and platform updates for operators, and what it is not.

The Katonic CLI is a small Python tool, installed as the `katonic-admin` command, for the people who run a self-hosted installation. The shorter `katonic` command belongs to the [Python SDK](/developers/libraries/python-sdk) and is not this tool. It verifies air-gap bundles, applies delta bundles, and carries catalog, pricing and telemetry updates between a running platform and Katonic. It is not a client for the public API: it has no chat, search or agent commands, never sends a `kapi_` key, and plays no part in a developer's own calls. For the public API use the reference with any HTTP client; for tools inside an AI client use the [Katonic MCP Server](/developers/libraries/mcp-server).

**Who can use it:** the team that operates the cluster. Day-one and day-two operations, including building and loading air-gap bundles, are done with `ktctl`, the platform operator's own tool, which the help centre documents under Install without internet access.

## Install

The tool lives in the platform repository as the `katonic-cli` package and is not published to a package index. Install it from a checkout of the repository:

```bash
pip install ./sdks/katonic-cli
katonic-admin --version
```

It needs Python 3.11 or later. It installs `click` and `rich`; without `rich` it prints plain text. Do not run `pip install katonic`: that name belongs to an older Katonic SDK from a previous generation of the product, not to this tool.

## Commands

| Command | What it does |
| --- | --- |
| `katonic-admin verify-bundle <bundle.tar.gz>` | Checks an air-gap bundle before deployment: the tarball opens, its manifest is present and is valid JSON with `version`, `components` and `bundle_type`, every image file the manifest lists is in the bundle, and each listed SHA-256 matches. `--manifest` names a different manifest file; `--strict` fails on warnings, such as no checksums to verify. |
| `katonic-admin diff-manifest --from <version> --to <version>` | Prints the components upgraded, added and removed between two versions as a table, or as JSON with `--output json`. |
| `katonic-admin apply-delta <delta.tar.gz>` | Applies a delta bundle: checks that the file is a tarball, imports each image archive with `ctr images import`, runs `helm upgrade katonic ./chart` in the namespace (`katonic` unless `--namespace` says otherwise) and waits up to ten minutes, then waits for the rollout with `kubectl`. `--dry-run` prints the steps instead; `--skip-verify` skips the check; `--kubeconfig`, or the `KUBECONFIG` variable, selects the cluster. |
| `katonic-admin update-mcp-catalog <catalog.json>` | Sends each MCP server entry of a catalog file to the admin API, one request per entry. The file is a list of entries or an object with a `servers` list. |
| `katonic-admin update-providers <pricing.json>` | Posts a provider pricing file, in the format of LiteLLM's model prices and context window file, to the admin API's provider sync. |
| `katonic-admin export-telemetry` | Reads usage metrics, error rates, published agents and models from the admin API and writes them to a JSON file, `telemetry.json` unless `--output` says otherwise, for Katonic support. User ids, email addresses, names and message content are replaced with hashes. `--days` records the window the export covers. |

The three commands that talk to the platform take `--api-url` (the `KATONIC_API_URL` variable; `http://localhost:8000` by default) and `--api-key` (the `KATONIC_API_KEY` variable, required), which is sent as a bearer token. The two update commands accept `--dry-run`, which lists what would be sent.

## Limits and behaviour

- On the current build, `diff-manifest` prints a representative table for any pair of versions rather than comparing the two versions' manifests; the components it names are fixed.
- `apply-delta` expects the chart at `./chart` in the working directory and the `ctr`, `helm` and `kubectl` binaries on the path. It checks only that the file is a tarball before applying it, so run `verify-bundle` first.
- On the current build the admin API has no routes at the paths the catalog, provider and telemetry commands call, so those commands cannot complete against a live platform; `--dry-run` shows what they would send. A connected platform receives catalog and pricing updates through OpsHub's catalog sync, and an air-gapped one through its seed bundle; see OpsHub, releases and licensing.
- The `katonic login` command belongs to the Python SDK, not to this tool. The tool on this page has no `login` command and never stores an API key; put the key in your own configuration or environment instead.

## Related

- [Libraries](/developers/libraries/overview)
- [Katonic MCP Server](/developers/libraries/mcp-server)
- Public API reference
- Install without internet access in the help centre

Source: https://docs.katonic.ai/developers/libraries/cli
