@kruntime/cli

@kruntime/cli owns the external developer CLI.

It composes:

image source directory
  -> @kruntime/kimage load
  -> @kruntime/komputer boot
  -> agent login
  -> action

It owns commands such as:

• komputer init
• komputer build
• komputer dev
• komputer test
• komputer login
• komputer run
• komputer exec
• komputer command
• komputer cron
• komputer snapshot
• komputer recover

Global options:

• --image dir: use an image source directory.
• --state path: use a persistent K state directory.
• --agent name: select an agent by name.
• --session id: use a stable session id.
• --mode normal|readonly|plan|limited: set the session mode.
• --model id-or-file: use a model id or model.yaml/model.json binding file.
• --models file: load model bindings from an explicit yaml/json file.
• --echo, --fake-model: use deterministic local echo model.
• --offline: use deterministic local echo model and skip provider setup.

Use -- before a prompt or shell script that starts with a dash:

komputer exec --image ./my-image -- 'echo --not-a-cli-option'

It does not own runtime policy. Runtime behavior belongs in @kruntime/komputer.

komputer snapshot writes a durable .kstate snapshot manifest for inspection or deployment handoff.

komputer build writes a .kimage/manifest.json and content-addressed blobs from an image source directory. The source digest ignores .kimage/, so building the package does not mutate the image identity.

komputer dev builds the image, boots a Komputer, logs in the selected Agent, and prints a ready status with commands, cron jobs, and model aliases. It is a simple development sanity check, not a separate runtime mode.

komputer login boots the image, logs in the selected Agent, and prints session status without sending a prompt.

komputer test first runs built-in smoke checks for build, boot, login, shell, and one Agent turn. If tests/**/*.test.ts or tests/**/*.test.js exist in the image directory, it then runs them with Node's test runner and passes K_IMAGE_DIR, K_STATE, and K_AGENT.

By default the CLI loads .env from the image directory, then overlays the current process environment. It uses real model providers when ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, MINIMAX_API_KEY, or OPENAI_API_KEY is present. Pass --echo or --fake-model for deterministic local tests. --offline also forces the echo model. Without a real provider or explicit fake/offline mode, model-backed actions fail with a setup error instead of silently pretending to use a model.

--model accepts either a model id or a model.yaml/model.json binding file. --models accepts an explicit binding file path when the image should keep a separate model config. Binding files are resolved from the image directory first, then the current working directory:

models:
  default:
    provider: deepseek
    model_id: deepseek-v4-flash
    api_key: env:DEEPSEEK_API_KEY
    base_url: env:DEEPSEEK_BASE_URL
    max_tokens: 4096

For DeepSeek's OpenAI-compatible endpoint, use:

models:
  default:
    provider: deepseek-openai
    model_id: deepseek-v4-flash
    api_key: env:DEEPSEEK_API_KEY

For MiniMax M2 interleaved-thinking through the OpenAI-compatible endpoint:

models:
  default:
    provider: minimax
    model_id: MiniMax-M2.7
    api_key: env:MINIMAX_API_KEY
    base_url: env:MINIMAX_BASE_URL
    extra: {"reasoning_split": true}
    max_tokens: 4096

Provider-specific fields stay in the adapter layer. OpenAI Responses may use include, reasoning, and store; chat-completion providers may use max_tokens, temperature, and extra; Anthropic-compatible providers may use max_tokens. Private thinking/reasoning fields are kept as provider metadata, not as portable K message text:

models:
  default:
    provider: openai-responses
    model_id: gpt-5.5
    api_key: env:OPENAI_API_KEY
    include: ["reasoning.encrypted_content"]
    reasoning: {"effort":"medium"}
    store: false

Runtime secrets are bound from common environment variables such as GITHUB_TOKEN and from K_SECRET_<NAME> entries.

The .env file is a local runtime input for the CLI. It is intentionally not included in .kimage build output.

komputer recover scans the .kstate session table and takes over sessions whose previous worker has detached or whose lease has expired. --include-closed also lists sessions that were explicitly ended with agent.close().