Kimi CLI Runner

Use this skill when you need to call Kimi Code CLI from the command line without entering the TUI.

If you are already running as Kimi, don't use this runner to re-invoke yourself. Keep the call in-host when available. This runner is for reaching Kimi from a different host (Codex / Claude / OpenCode / etc.) for cross-model review, drafting, or synthesis.

Preconditions

• kimi is installed: command -v kimi
• python3 is version 3.10 or newer. Older runtimes are rejected before model invocation because the shared monotonic deadline must use the same clock reference across processes.
• You are authenticated/configured for Kimi Code CLI. First-time setup is usually kimi login or /login inside the TUI.
• The official package is @moonshot-ai/kimi-code and the executable is kimi.

The exposed command interface was checked against local Kimi Code 2.0.2 and the official CLI reference on 2026-10-01. This metadata check does not establish account readiness or successful inference. Prompt mode uses:

kimi -p "prompt text" --output-format stream-json

Kimi Code currently exposes -p, --prompt <prompt> for headless prompt mode. It does not expose a --prompt-file or stdin prompt flag, so the runner keeps a file-based interface but must pass the merged prompt as one CLI argument internally. Very large prompt packets can exceed OS argument limits; the script fails early with a clear message when the merged prompt is over the configured limit.

Recommended: runner script

SKILL_DIR="${SKILL_DIR:-$(for r in "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${CODEX_HOME:-$HOME/.codex}" "$HOME/.config/opencode" "$HOME/.kimi-code"; do [ -d "$r/skills/kimi-cli-runner" ] && echo "$r/skills/kimi-cli-runner" && break; done || true)}"
bash "${SKILL_DIR}/scripts/run_kimi.sh" \
  --system-prompt-file /path/to/system.txt \
  --prompt-file /path/to/prompt.txt \
  --out /path/to/output.txt

With an explicit model and read/write workspace exposure:

SKILL_DIR="${SKILL_DIR:-$(for r in "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${CODEX_HOME:-$HOME/.codex}" "$HOME/.config/opencode" "$HOME/.kimi-code"; do [ -d "$r/skills/kimi-cli-runner" ] && echo "$r/skills/kimi-cli-runner" && break; done || true)}"
bash "${SKILL_DIR}/scripts/run_kimi.sh" \
  --model kimi-code/kimi-for-coding \
  --tool-mode workspace \
  --workspace-dir /path/to/project \
  --prompt-file /path/to/prompt.txt \
  --out /path/to/output.txt

Dry-run:

SKILL_DIR="${SKILL_DIR:-$(for r in "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${CODEX_HOME:-$HOME/.codex}" "$HOME/.config/opencode" "$HOME/.kimi-code"; do [ -d "$r/skills/kimi-cli-runner" ] && echo "$r/skills/kimi-cli-runner" && break; done || true)}"
bash "${SKILL_DIR}/scripts/run_kimi.sh" \
  --model kimi-code/kimi-for-coding \
  --prompt-file /path/to/prompt.txt \
  --out /path/to/output.txt \
  --dry-run

Safety notes

• Kimi Code prompt mode rejects --plan, --auto, and --yolo combined with --prompt.
• Do not add -y to prompt mode. The runner rejects the conflicting --yolo option before invocation.
• Kimi prompt mode is not a sandbox: it can run tools with automatic approval. Use this runner only with trusted prompts or in an external disposable environment.
• To reduce accidental repo exposure, this runner defaults to --tool-mode isolated, which runs kimi -p from a temporary isolated working directory and passes no --add-dir.
• By default, the runner also passes an empty temporary --skills-dir, which prevents Kimi from auto-discovering user/project skills during isolated runs.
• Use --tool-mode workspace only when Kimi should see a real project. That mode still runs from a temporary working directory but passes each workspace with Kimi's official --add-dir DIR.
• --tool-mode isolated reduces accidental exposure; it is not an OS sandbox and does not prove Kimi cannot access absolute paths or run shell commands.
• --tool-mode workspace is explicit workspace access, not a read-only guarantee. Use it only with prompts that are allowed to read or modify that workspace.

Notes

• The runner defaults to --output-format stream-json and writes only assistant text content to --out; tool calls, tool results, metadata, and non-text assistant blocks are not represented in that output file.
• Tool result and metadata events are ignored in parsed output.
• Kimi Code may spend a long time in thinking or tool-use before emitting final assistant text. --timeout-secs bounds the entire invocation, including retries, fallback and backoff (no hard deadline by default; an explicit positive value is a hard cap). Expiry and cancellation terminate locally created CLI process groups and their descendants. This does not attest cancellation of a remote provider job.
• If a specific --model fails with a model-not-found style error, the runner retries with Kimi's configured default model unless --no-fallback is set.
• --max-attempts caps all CLI calls in this invocation; fallback consumes the same remaining budget. --sleep-secs backoff consumes the same deadline. Quota exhaustion, the reported billing-cycle usage-limit wording and deterministic permission refusals stop instead of repeating the blocked call. These phrases in successful assistant prose do not turn a completed body into an error; classification runs on failed calls/error diagnostics.
• Exit 0 requires nonblank assistant text and successful execution without an error event. Interrupted text is retained as OUT.partial, without a completed OUT. Every call's raw events, diagnostics and budget receipt remain under OUT.attempts/run.* (or --trace-dir DIR). Requested model aliases are recorded; actual provider model identity remains unknown unless separately attested. A completed invocation is not scientific acceptance.
• Deterministic failures (usage/auth/region-ineligibility errors, exit codes 2/126/127, and similar, detected from the exit code and diagnostics) fail immediately with the diagnostic instead of burning the retry backoff; model-not-found keeps its default-model fallback.
• The merged prompt limit defaults to a conservative OS-argument-safe value. Override with KIMI_MAX_PROMPT_BYTES when you know your platform can accept larger prompt arguments.
• Repeat --skills-dir DIR to pass Kimi Code skill directories through to the run. Per official Kimi docs, specifying this flag replaces auto-discovered user and project skill directories.
• Pass --auto-skills only when you intentionally want Kimi to auto-discover user/project skills; it is mutually exclusive with explicit --skills-dir.
• Use kimi provider list --json to inspect the model aliases configured on the current machine before setting --model.
• Use --dry-run for offline validation. It prints paths, sizes, hashes, and planned flags, but never prints the full prompt.

Session continuation

• --resume-session ID — resume a specific recorded Kimi session (kimi -S ID); the prompt becomes that session's next turn. Treat IDs as opaque and pass the exact ID reported by the installed CLI; do not add or strip a historical prefix.
• --continue-work-dir — continue the previous session OF THE WORKING DIRECTORY (kimi -c). Kimi scopes -c per working directory — confirmed both by the CLI help and by the on-disk sessions/wd_<dir-hash>/ layout — so this is non-racy across parallel runs in different directories. Requires --work-dir DIR pointing at the prior run's directory (the runner's default isolated fresh temp dir has no previous session): run 1 with --work-dir D, run 2 with --work-dir D --continue-work-dir.

Continuation requires the original working directory and recorded session identity. It continues the same execution and does not count as independent review. Current metadata-only checks do not establish live session recovery for a configured provider.

Options