using/cli

$ lash
# Setup wizard:
# 1. Choose a provider (Anthropic, OpenAI, OpenAI-compatible, Codex, Google OAuth)
# 2. Paste API key (or run OAuth / device-code flow)
# 3. Optionally paste a Tavily API key for the built-in web-search tool
# 4. Choose standard or RLM; if RLM, choose lashlang or typescript
# 5. Drop into the interactive TUI

Re-run the wizard at any time with lash --provider. Use /provider from inside a session to switch providers without restarting.

$ lash --print "Summarise this branch's changes in two bullets."
# Assistant prose to stdout, tool/lifecycle logs to stderr:
#   [tool] exec_command · ok · 41ms
#   [tool] read_file · ok

$ lash --print "Investigate the latest test failure." \
       --await-background-work \
       --turn-usage-json out/usage.json

$ lash --mode json --print "Summarise this repository."
{"type":"turn_start","protocol_version":1,"stream_id":1}
{"type":"event","stream_id":1,"activity":{"id":"a1","correlation_id":"c1","type":"model_request_started","protocol_iteration":0}}
{"type":"event","stream_id":1,"activity":{"id":"a2","correlation_id":"call-3","type":"tool_call_completed","call_id":"call-3","name":"exec_command","args":{"...":"..."},"output":{"...":"..."},"duration_ms":41}}
{"type":"turn_finish","stream_id":1,"ok":true,"cancelled":false,"assistant_text":"...","outcome":{...},"usage":{...},"children_usage":[],"errors":[],"execution":{...},"tool_calls":[...]}

Each event wraps one TurnActivity: an id, a correlation_id, and a flattened TurnEvent tagged by type. Tool events report the runtime tool name (exec_command), not the shell.exec surface path; see the Lash SDK's event vocabulary and stability contract.

RPC mode starts a reusable session and reads one JSON object per line from stdin. It opens with a ready record ({"type":"ready","protocol_version":1,"protocol":"lash.rpc.v1","methods":["prompt","ping","shutdown"]}). A prompt request streams turn_start, event, and turn_finish records tagged with the request id, then writes a final response.

{"id":1,"method":"prompt","params":{"prompt":"List the top-level crates."}}
{"id":2,"method":"shutdown"}

{
  "active_provider": "openai",
  "charge_safety": { "mode": "require_guarantee" },
  "execution_mode": "rlm",
  "rlm_dialect": "typescript",
  "providers": {
    "openai": { "type": "openai", "api_key": "sk-..." },
    "anthropic": {
      "type": "anthropic",
      "api_key": "sk-ant-...",
      "options": {
        "cache_retention": "long",
        "max_output_tokens": 16384,
        "reliability": {
          "response_start_timeout": 30000
        }
      }
    }
  },
  "auxiliary_secrets": {
    "tavily_api_key": "tvly-..."
  },
  "mcp_servers": {
    "docs": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-server-docs"],
      "graceful_period_ms": 3000,
      "post_kill_wait_ms": 1000
    }
  },
  "agent_models": {},
  "model_defaults": {
    "openai": { "model": "openai/gpt-5.5", "variant": "medium" }
  }
}

By default, Lash requires a provider idempotency or resume guarantee before retrying a generation that may already have been billed. To accept bounded duplicate billing, set this top-level config key:

"charge_safety": {
  "mode": "accept_duplicate_billing",
  "max_unsafe_retries": 2,
  "max_duplicate_cost_tokens": 2000
}

Lash clamps max_unsafe_retries to at most five per logical LLM call. The optional token bound counts input, output, cache-read, and cache-write tokens already billed for the abandoned generation. Missing partial usage counts as zero toward this bound, so it cannot cap unknown charges; the retry-count limit still applies. Omit max_duplicate_cost_tokens or set it to null for no token bound. Nonretryable failures remain nonretryable. This is configuration, with no CLI flag.

Provider retry settings live under providers.<kind>.options.reliability.retry. ProviderRetryPolicy.jitter_ms defaults to 500 milliseconds of per-attempt additive random jitter; 0 disables it. retry_after_cap_ms defaults to 60000 (60 seconds). A longer server Retry-After now refuses immediately instead of sleeping a truncated delay.

Failed-turn diagnostics show the charge refusal code, billed tokens, and whether partial output exists. Zero usage is labeled as reported or defaulted because the evidence does not distinguish missing usage from a reported zero. Partial text stays out of the terminal timeline. Advisory issues render as warnings, and omitted tool records disclose their counts. JSON/RPC finish records also carry failure_evidence and omitted.

This pin is a forward-only, whole-home runtime-data cutover. Older session, process, trigger, and effect-replay databases are refused before provider startup; there is no migration chain. Retain or export needed data with the old compatible binary first. Then run lash --reset and confirm to remove the entire runtime store and session roster together, preserving provider configuration. Never reset databases piecemeal. Old trace files need a compatible reader; remote peers need matching protocol versions.

/fork branches the current session at the current message and opens the fork in a new terminal window. Lash resolves the launcher from the running executable and falls back to finding lash on $PATH if that binary isn't launchable. The launched fork runs lash --resume <new-session-id> in the new terminal.