Installation

```bash

Go install

go install github.com/diillson/chatcli@latest

Quick Setup

LLM_PROVIDER=OPENAI    # OPENAI, CLAUDEAI, BEDROCK, GOOGLEAI, XAI, ZAI, MINIMAX, MOONSHOT,
                       # COPILOT, OLLAMA, STACKSPOT, OPENROUTER
OPENAI_API_KEY=sk-xxx

<details> <summary><strong>Full provider configuration reference</strong></summary>

Removed provider — GitHub Models. GitHub retired GitHub Models on July 30 2026 (playground, model catalog, inference API and BYOK, for every customer), so the GITHUB_MODELS provider was dropped. The env vars GITHUB_MODELS_MODEL, GITHUB_MODELS_TOKEN, GITHUB_MODELS_MAX_TOKENS and GITHUB_MODELS_API_URL no longer have any effect, and GITHUB_MODELS is no longer accepted as a provider value (including in the operator's Instance CRD). GitHub Copilot is a different product and is unaffected — if you were on GitHub Models for OpenAI models, COPILOT or OPENAI are the direct replacements.

Environment file (.env) discovery

ChatCLI looks for its environment file in this order, and the first file that exists wins:

1. $CHATCLI_DOTENV (explicit; honored even when missing, so a typo is reported instead of silently ignored)
2. ./.env — the working directory
3. ~/.chatcli/.env
4. ~/.env

The home fallbacks matter for the non-interactive surfaces: an editor spawning chatcli acp, or an MCP client spawning chatcli mcp-server, does not run your shell profile — CHATCLI_DOTENV and any variable you export from .zshrc/.bashrc never reach the child process, and its working directory is the project, which usually has no .env. Before this fallback existed those servers ran with no environment file at all: providers keyed by an env var disappeared and AWS_PROFILE went missing, so Bedrock authenticated as the default profile instead of the account you logged into. Keep your file at ~/.chatcli/.env (or ~/.env) and every surface agrees. /config shows the file in effect, its origin, and the effective AWS profile.

Per-project settings: the ACP server also layers the .env of the project the editor opened (session/new's cwd) on top, fill-only — it can add variables you have not set, never override one already in effect, and only the first project announced applies. Because a project directory is untrusted input, CHATCLI_PROJECT_ENV=safe (the default) refuses credential and endpoint variables (*_API_KEY, *_TOKEN, *_BASE_URL, *_API_URL, …) from that file; all accepts everything, off disables the overlay.

Custom endpoints and OpenAI-compatible gateways

• OPENAI_API_URL overrides the OpenAI chat completions endpoint. It must be the full chat completions URL (e.g. https://gateway.example.com/v1/chat/completions) — the /models listing URL is derived from it.
• Authentication is unchanged: requests carry Authorization: Bearer $OPENAI_API_KEY, so when redirecting to a gateway set OPENAI_API_KEY to the gateway's key. Do not combine a third-party URL with an OAuth login (/auth login openai) — the OAuth token would be sent to the gateway.
• OPENAI_RESPONSES_API_URL overrides the Responses API endpoint. A custom OPENAI_API_URL (different host) forces the chat completions surface — the catalog preference for the Responses API (e.g. gpt-5.4, the default) only applies on the official host, so a gateway key is never sent to api.openai.com. Effective precedence: OAuth > OPENAI_USE_RESPONSES=true > custom OPENAI_API_URL host (chat completions) > model catalog preference > OPENAI_USE_RESPONSES=false. If your gateway does expose the Responses API, opt in with OPENAI_USE_RESPONSES=true and set OPENAI_RESPONSES_API_URL too.
• When the endpoint URL points to a custom host, the model listing is not filtered by model family — every model the gateway returns on /models appears in the autocomplete and /switch --model. Against the official endpoint, the listing keeps only chat-capable families (hiding embeddings, whisper, tts, dall-e, moderation). The same rule applies to ZAI_API_URL, MOONSHOT_API_URL and MINIMAX_API_URL.
• To use a third-party OpenAI-compatible gateway as a provider separate from OpenAI (including in the server fallback chain), point the OpenRouter preset at it: LLM_PROVIDER=OPENROUTER with OPENROUTER_API_KEY and OPENROUTER_API_URL=https://gateway.example.com/v1/chat/completions.

Z.AI GLM Coding Plan (subscription)

• ZAI_USE_CODING_PLAN=true points the ZAI provider at the subscription endpoint (https://api.z.ai/api/coding/paas/v4/chat/completions). The same platform API key works on both endpoints — the /coding/ path is what makes requests draw from the plan instead of pay-as-you-go credits.
• The plan serves glm-5.3 and glm-5.3-flash; requests for older GLM ids are routed to them server-side. /cost reports these calls at $0: usage is covered by the subscription, not billed per token.
• An explicit ZAI_API_URL always wins over the toggle — set it to the full chat completions URL (e.g. the mainland endpoint https://open.bigmodel.cn/api/coding/paas/v4/chat/completions). Any URL with an /api/coding/ path is treated as plan usage.
• ZAI_THINKING=enabled|disabled controls the GLM thinking mode on both the plain and tool-calling paths (unset keeps the backend default; enabled also preserves interleaved reasoning across turns).

</details>

---

Deploy + K8s wait + trigger smoke

/schedule deploy --when +0s --do "shell: terraform apply -auto-approve" \ --wait "k8s:deployment/prod/api:Available" --timeout 15m \ --triggers smoke-tests

Configurable fallback chain

CHATCLI_FALLBACK_PROVIDERS=OPENAI,CLAUDEAI,BEDROCK,ZAI,MINIMAX,MOONSHOT,OPENROUTER ```

/thinking on|off|auto enables extended thinking / reasoning_effort on any provider that supports it — the cross-provider mapping is automatic.

---

Daemon to keep running with the CLI closed

chatcli daemon start --detach chatcli daemon status

Command Reference

---

Harness/Quality Pipeline

Seven prompting/execution patterns composed via a pluggable pipeline with state machine, hot reload, and per-hook isolation.

Pipeline Architecture

• State machine (Active → Draining → Closed) with atomic CAS transitions.
• Copy-on-Write via atomic.Pointer[snapshot] — AddPre/AddPost/SwapConfig are atomic, zero locks on the hot path.
• Per-hook isolation: panic recovery, timeout enforcement (default 30s), circuit breaker (5 failures → open for 30s).
• Priority-based ordering via optional Prioritized interface (backward-compatible — unmarked hooks default to 100).
• Short-circuit sentinels: ErrSkipExecution (cache-hit before agent.Execute) and ErrSkipRemainingHooks (ensemble patterns).
• Graceful shutdown via DrainAndClose(timeout) honoring in-flight calls.