LLM Setup

Commando uses an LLM to plan each command. You can use OpenAI, OpenRouter, or skip the LLM entirely with the deterministic mock planner.

Quick decision

Interactive setup

cmdo init

This prompts you for:

1. Provider — openai or openrouter.
2. API key — pasted at the prompt, stored in ~/.commando/config.json.
3. Model — picked from a curated dropdown.

Re-run cmdo init any time to switch providers or models.

Manual / env-only setup

If you'd rather not store the key on disk, set env vars and skip cmdo init. Commando looks for env vars before falling back to ~/.commando/config.json.

export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=gpt-4o-mini   # optional, defaults to gpt-4o-mini

export OPENROUTER_API_KEY=sk-or-...
export OPENROUTER_MODEL=z-ai/glm-4.5-air:free   # optional

On Windows PowerShell:

$env:OPENAI_API_KEY = "sk-..."
$env:OPENAI_MODEL   = "gpt-4o-mini"

Curated OpenAI models

The cmdo init picker keeps the list tight (one screen). Power users can override via OPENAI_MODEL.

Default: gpt-4o-mini.

OpenRouter

OpenRouter exposes a single OpenAI-compatible endpoint that proxies to dozens of providers. The default model z-ai/glm-4.5-air:free works without spend, which makes it ideal for first-run testing.

Default: z-ai/glm-4.5-air:free.

Override with OPENROUTER_MODEL (e.g. anthropic/claude-3.5-sonnet, openai/gpt-4o-mini, meta-llama/llama-3.1-70b-instruct).

How Commando uses the LLM

The planner sends a hard-rules system prompt plus a scoped slice of AGENT.md (only the section for the routed binary). It expects a single JSON object back:

{
  "binary": "sui",
  "args": ["client", "active-address"]
}

Output is parsed defensively (markdown fences, smart quotes, and surrounding prose are all tolerated). The plan is then validated against the allowlist built from AGENT.md:

• binary must be one of sui / walrus / site-builder (with the platform-correct suffix).
• The leading non-flag tokens of args must form a real command path.
• Every flag must exist in the skill contract for that command path.

A failed validation triggers a retry with a tighter hint instead of executing a hallucinated command.

Offline / demo mode

Set CMDO_LLM_MOCK=1 to bypass the LLM entirely:

CMDO_LLM_MOCK=1 cmdo "show sui client active address" --sui

The mock covers:

• Sui — client active-address, client active-env, client new-address, client gas, client switch --env, client publish, move build, move test.
• Walrus — info, list-blobs, get-wal, basic store/read scaffolding.
• Site-builder — deploy <DIRECTORY> --epochs <N>, sitemap, update.

Use it for hackathon demos, CI smoke tests, or to rule out the LLM as a source of bugs while debugging.

Cost notes

• gpt-4o-mini typically costs less than $0.001 per planning call (the prompts are small — usually under 2 KB).
• OpenRouter free tiers have rate limits; switch to a paid model if you hit them during a demo.
• The planner makes one LLM call per cmdo invocation under happy path; one extra call per validation retry (max 2 retries by default).

Next