The Katonic CLI
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 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.
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:
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-manifestprints a representative table for any pair of versions rather than comparing the two versions' manifests; the components it names are fixed. apply-deltaexpects the chart at./chartin the working directory and thectr,helmandkubectlbinaries on the path. It checks only that the file is a tarball before applying it, so runverify-bundlefirst.- 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-runshows 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 logincommand belongs to the Python SDK, not to this tool. The tool on this page has nologincommand and never stores an API key; put the key in your own configuration or environment instead.
Related
- Libraries
- Katonic MCP Server
- Public API reference
- Install without internet access in the help centre