kamiwaza-cli
The kamiwaza operator CLI — a standalone cross-substrate command-line
tool for Kamiwaza deployments. Talks to control-plane, data-store,
identity, ingress, model-serving, and batch-execution components through
the kamiwaza-sdk; adds OIDC login and local context management, a
k9s-style operator cockpit (kamiwaza ui) with matching one-shot resource
verbs, model acquisition + provider configuration, cluster PKI/DNS tooling, and a configurable support-bundle pipeline with an offline diagnostic dashboard
viewer on top.
Install
Install from PyPI as an isolated tool, pinned to a release:
uv tool install "kamiwaza-cli==2.0.0"
# or
pipx install "kamiwaza-cli==2.0.0"
Requires Python 3.11+.
Kamiwaza engineers with access to the source repository can install it for development:
git clone git@github.com:kamiwaza-mde/kamiwaza-cli.git
cd kamiwaza-cli
python -m pip install -e ".[dev]"
Optional extras
The interactive operator console (kamiwaza ui) is part of the base install.
Kubernetes-native resource kinds stay behind an extra so the base stays lean:
uv tool install "kamiwaza-cli[k8s]==2.0.0" # + Kubernetes-native kinds (orchestrated)
# or
pipx install "kamiwaza-cli[k8s]==2.0.0"
See docs/ui.md. The k8s extra adds in-process Kubernetes
access (no external tools) and only activates on orchestrated deployments
with usable cluster credentials.
Quickstart
kamiwaza login # OIDC flow against the deployment
kamiwaza context list # see registered deployments
kamiwaza status # one-page cluster status (exit 0 = HEALTHY)
kamiwaza diagnose # health check across components
kamiwaza logs control-plane --since 10m
kamiwaza support-bundle collect -o bundle.tar.gz
kamiwaza support-bundle view bundle.tar.gz # offline dashboard in your browser
kamiwaza ui # interactive k9s-style cockpit
See docs/getting-started.md for the
workstation-to-first-diagnose walkthrough.
Login
kamiwaza login is OAuth 2.0 Authorization Code + PKCE against your
deployment's Keycloak realm. On a workstation it opens a browser; you
sign in with your Keycloak credentials, approve, and the browser
closes. Token + refresh-token are cached on disk (~/.kamiwaza/contexts/<name>/token.json,
mode 0600); subsequent commands silently re-use them and silently
refresh as needed.
# 1. Register the deployment (once per workstation):
kamiwaza context add prod --endpoint https://kamiwaza.prod.example/ --use
# 2. Log in:
kamiwaza login
# → browser opens → Keycloak login page → enter credentials → approve.
# 3. Use any authenticated command — no per-command auth dance:
kamiwaza diagnose
kamiwaza logs control-plane --since 10m
One-time deployment setup: register the CLI's OIDC client
kamiwaza login needs a public OIDC client named kamiwaza-cli
registered in your deployment's Keycloak realm. Production deployments
should ship this in their installer (Helm chart / Terraform); for ad-hoc
deployments you can register it once by hand. In the bundled debug
container this is automatic — see "Debug container shortcut" below.
Option A — Keycloak Admin UI (90 seconds)
- Open
https://<your-deployment>/admin/master/console/and log in asadmin(password in thekamiwaza/keycloak-admincluster secret). - Top-left dropdown → switch realm to
kamiwaza. - Clients → Create client:
- Client type: OpenID Connect
- Client ID:
kamiwaza-cli - Next
- Capability config:
- Client authentication: OFF (public client; required for PKCE)
- Authentication flow: tick Standard flow and Device authorization grant; untick the rest
- Next
- Login settings:
- Valid redirect URIs:
http://127.0.0.1:*/callback,http://localhost:*/callback - Web origins:
+ - Save
- Valid redirect URIs:
- Open the new client → Advanced tab → Proof Key for Code Exchange Code Challenge Method: S256 → Save.
Option B — kcadm (one shell-out, scriptable)
KCADMIN=$(kubectl -n kamiwaza get secret keycloak-admin -o jsonpath='{.data.password}' | base64 -d)
KCPOD=$(kubectl -n kamiwaza get pod -l app.kubernetes.io/name=keycloak -o name | head -1)
kubectl -n kamiwaza exec "$KCPOD" -- /opt/keycloak/bin/kcadm.sh \
config credentials \
--server http://localhost:8080 \
--realm master --user admin --password "$KCADMIN"
kubectl -n kamiwaza exec "$KCPOD" -- /opt/keycloak/bin/kcadm.sh \
create clients \
--target-realm kamiwaza \
--set clientId=kamiwaza-cli \
--set publicClient=true \
--set 'redirectUris=["http://127.0.0.1:*/callback","http://localhost:*/callback"]' \
--set 'webOrigins=["+"]' \
--set standardFlowEnabled=true \
--set 'attributes={"oauth2.device.authorization.grant.enabled":"true","pkce.code.challenge.method":"S256"}'
Debug container shortcut
When kamiwaza login runs inside the kamiwaza-debug container
(jump pod, ephemeral kubectl debug, or DaemonSet shell), the
container's kamiwaza wrapper auto-provisions the kamiwaza-cli
client on the realm if it's missing. It uses the pod's existing RBAC
to read the kamiwaza/keycloak-admin secret and exec into the
Keycloak pod's kcadm.sh. Idempotent (probes the realm first), runs
once per pod lifetime, no operator interaction. Outside the debug pod
the wrapper is a transparent passthrough — see Options A/B above for
your workstation.
From a headless environment (SSH, in-pod, no browser)
kamiwaza login --device-code
# → prints "visit https://kamiwaza.test/realms/kamiwaza/device?user_code=XXXX-XXXX"
Open that URL on any device with a browser, enter the code, approve. The CLI is polling and finishes automatically.
Multiple contexts
kamiwaza context add prod --endpoint https://kamiwaza.prod.example/
kamiwaza context add staging --endpoint https://stg.example/
kamiwaza --context prod diagnose # one-off override
kamiwaza context use staging # switch the active context
Tokens are scoped per context — logging in against staging doesn't
disturb prod credentials.
TLS — private CAs and dev clusters
For deployments using a private CA, pin the bundle on the context once:
kamiwaza context add prod \
--endpoint https://kamiwaza.prod.example/ \
--ca-bundle /etc/ssl/private/kamiwaza-prod-ca.pem \
--use
Stored at ~/.kamiwaza/contexts/<name>/ca.pem (mode 0600), auto-loaded
for every command — no KAMIWAZA_CA_BUNDLE env var dance. Mirrors
aws --ca-bundle and gcloud --certificate-authority.
For local-dev clusters with self-signed certs you don't want to bother pinning:
kamiwaza context add dev \
--endpoint https://kamiwaza.dev.local/ \
--insecure-skip-tls-verify --use
kubectl-style flag — disables verification entirely for that context.
Production contexts should always pin a bundle instead.
Agent and script contract
kamiwaza schema describes the installed command tree without credentials,
configuration, or a platform connection. Use kamiwaza schema context list
to inspect one command's required arguments, options, types, and choices.
The JSON schema_version is 1.0; it is an installed-CLI discovery format,
not a claim of full CLI Spec or CLI Agent Spec conformance.
kamiwaza schema
kamiwaza schema context list
kamiwaza --output json --non-interactive --no-color context list
Place global flags before the command path. Commands with a platform target
also accept --context NAME. JSON successes write data to stdout. JSON errors
write a single envelope to stderr with a stable kind, summary, next_step,
and exit_code; always check process status. Some diagnostic and support-bundle
commands use nonzero outcomes for findings, not failed changes.
--non-interactive refuses terminal prompts and editors. Without a TTY,
commands requiring input also refuse; supply existing command-specific flags
only after reviewing consequences. There is no global --yes, --dry-run,
or --no-pager: no pager runs automatically. The schema does not certify a
command's side effects, result shape, or retry safety. Inspect the command's
help and current target state before a mutation; never retry uncertain writes
blindly. Never pass credentials as CLI arguments.
Commands
| Command | Purpose |
|---|---|
kamiwaza schema [path ...] |
Discover installed commands and flags offline as JSON |
kamiwaza login / logout |
OIDC login (Auth Code + PKCE or --device-code); discard tokens (--all) |
kamiwaza context * |
Register / switch between multiple deployments |
kamiwaza status / events |
One-page cluster status (exit 0 = HEALTHY); recent Kubernetes Warning events |
kamiwaza diagnose |
Run the built-in health checks across canonical components |
kamiwaza dns check|resolve |
Read-only DNS troubleshooting; resolve a name with the cause |
kamiwaza logs <component> |
Stream logs from a named component |
kamiwaza restart <component> |
Restart a component (live-integration-tested) |
kamiwaza kinds / get / describe / edit / delete / action |
Universal resource verbs over every kind the cockpit manages |
kamiwaza model search|pull|status |
Acquire models — search a hub, download weights, or register a provider model |
kamiwaza provider add|list|show|remove |
Configure model providers (e.g. AWS Bedrock) |
kamiwaza certs * |
Cluster PKI: inventory, renew, rotate-ca, install, trust anchors, TLS test |
kamiwaza user * |
Identity-management operations against the deployment's user surface |
kamiwaza support-bundle collect|view|analyze|list-* |
Redact-aware bundle pipeline + offline dashboard viewer |
kamiwaza ui |
Interactive command center (k9s-style TUI) |
kamiwaza version |
CLI + SDK version info |
Full reference: docs/commands.md.
Documentation
docs/getting-started.md— fresh laptop → firstkamiwaza diagnosedocs/commands.md— every subcommand, flag, exit codedocs/support-bundle.md— operator guide for the bundle pipelinedocs/publishing-bundle-spec.md— publish a deployment-specific spec at the well-known pathdocs/oidc-client-setup.md— wire up the deployment's identity providerdocs/runbooks/— one runbook per canonical diagnose failurespecs/— the spec-kit source of truth for every feature (spec.md/plan.md/tasks.md/contracts/)
Development
python -m pip install -e ".[dev]"
pytest tests/unit/kamiwaza_cli # default test suite
pytest -m browser tests/browser # dashboard Playwright tests (requires `playwright install chromium`)
ruff check kamiwaza_cli tests/unit/kamiwaza_cli
ruff format kamiwaza_cli tests/unit/kamiwaza_cli
Integration tests (tests/integration/kamiwaza_cli/) are gated on
KAMIWAZA_TEST_ENDPOINT + KAMIWAZA_TEST_TOKEN per Constitution
Principle VII; skipped by default.
Architecture
The CLI is a single Python package (kamiwaza_cli/) installed as the
kamiwaza console script. Entry point is kamiwaza_cli.cli:main.
Layout at the repo root:
kamiwaza_cli/ Python package source
specs/ spec-kit source of truth (001–004)
tests/ unit / integration / browser / perf / fixtures
docs/ operator-facing reference + runbooks
.specify/ spec-kit templates + constitution
scripts/ developer scripts (fault sweeps, host-file verifier)
demo/ local demo harness for the spec-003 dashboard
Design detail, hard rules, and the reuse contract live in
CLAUDE.md. The constitution is at
.specify/memory/constitution.md.
Platform installation and upgrades use the Deploy repository's native install interface
with a KKS-prepared substrate. The former kamiwaza cluster sync command has been
removed (ENG-11941); see cluster installation guidance.
License
Apache-2.0.
Metadata
Release files for kamiwaza-cli 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kamiwaza_cli-2.0.0.tar.gz | 668.1 kB | With provenance | Details for kamiwaza_cli-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kamiwaza_cli-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for kamiwaza_cli-2.0.0-py3-none-any.whl |
Total release size: 1.5 MB
Release files / kamiwaza_cli-2.0.0.tar.gz
| Download URL | kamiwaza_cli-2.0.0.tar.gz |
|---|---|
| Size | 668.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cd3554effb2a53d965d49341cfb66097657debd8b01bb459c0fc0f1aace432b4
|
|
BLAKE2b-256 checksum How to use checksums |
2569a46b6fd28823aef5951ab23a2258b76478c8fdf8f1d1713e8bbd4fcb3094
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / kamiwaza_cli-2.0.0-py3-none-any.whl
| Download URL | kamiwaza_cli-2.0.0-py3-none-any.whl |
|---|---|
| Size | 810.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
35c10aa6babf3e0c2e35270c54b2207aad8607f2f81ff6f7b5c04df4f843c129
|
|
BLAKE2b-256 checksum How to use checksums |
1abe7f34c0de79dda9749afab58eaacb041e24033179f613969415440ea42b27
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for kamiwaza-cli 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for kamiwaza_cli-2.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.