CLI Agents Reference Guide¶

← Back to the main path README · A1: Safely run your first small task

This reference doc organizes 9 terminal CLIs around “what do you want to do now?” and checkable official sources. It does not score tools or choose an entry point by popularity or subjective ranking; first identify the role, then choose based on your provider, sign-in method, and safety boundaries.

First separate the roles: an agent is not a model or API¶

Type	What it does	Examples	Do not confuse it with
LLM	Generates text, code, or tool calls	Claude, GPT, Gemini	The model does not automatically have access to files on your computer
Provider API	Provides requests, authentication, and billing for one model provider	Anthropic API, OpenAI API, Gemini API	An API is not a terminal workbench
Router	Forwards requests to multiple providers	OpenRouter	A Router does not manage files or command permissions on an agent’s behalf
Coding agent / harness	Reads files, edits, runs commands, and reports results in the terminal	Claude Code, Codex, OpenCode, Pi	Its approval, sandbox, and project trust settings need separate checking
Local runtime	Loads and runs a model locally	Ollama	It can be called by an agent, but it is not a coding agent

Find an entry point from your situation¶

Your situation	What to check first	Differences to record
You already have an account with a model service	A CLI from that ecosystem, such as Claude Code, Codex, or Gemini CLI	Sign-in flow, approval, sandbox, and usage page
You need to switch providers	OpenCode, goose, Aider, Hermes Agent, or Pi	Supported endpoints, model IDs, and where API keys are stored
You want to route multiple providers through one place	OpenRouter paired with an agent	The actual provider route, data policy, usage, and billing
You want to practice locally	Ollama paired with an agent that supports a compatible API	Whether the model is local, and whether the agent can still run shell commands / write files

9 CLI tools¶

The full table is collapsed by default; after expanding it, record the “checked on” date alongside your installed version. Official data checked on: 2026-08-30 UTC.

Expand installation, authentication, provider, and safety facts for the 9 CLIs

Type	Tool	Who it currently suits	Model / provider choices	Sign-in method	Safe starting point	Status	Official sources
Official model ecosystems	Claude Code	People who want to use the Anthropic ecosystem in the terminal	Claude; Anthropic API	Claude account or Anthropic API key	Use a demo repo; keep the permission prompt	One of Anthropic’s official terminal, desktop, IDE, and cloud interfaces	docs · repo
	Codex CLI	People who want to use OpenAI / ChatGPT sign-in in the terminal	GPT family; OpenAI API	ChatGPT sign-in or OpenAI API key	Use the default approval and workspace sandbox; inspect the diff first	OpenAI’s open-source terminal coding agent	docs · repo
	Gemini CLI	People with Google authentication who want Gemini in the terminal	Gemini; Google AI API or Vertex AI	Google sign-in, Gemini API key, or Vertex AI	Use approval mode; explicitly enable `--sandbox` when needed	Google’s open-source terminal agent	docs · repo
	Grok Build	People who want to try xAI’s Grok terminal TUI	Grok; xAI sign-in or API key	Interactive browser sign-in on first launch; CI can use `XAI_API_KEY`	Start in a demo repo; do not copy `~/.grok/auth.json`	xAI’s official open-source TUI coding agent	authentication · repo
Provider-flexible	OpenCode	People who need to switch among multiple providers	Multiple providers; can connect to OpenRouter or a compatible endpoint	Configure an API key, OAuth, or environment variable for the provider	Check permission settings first; test outside directories only in a demo repo	Open-source terminal coding agent; `AGENTS.md` has priority, with `CLAUDE.md` as a compatibility fallback when absent	provider · repo
	goose	People who need a CLI, desktop app, or API and want to connect tools and data sources	15+ providers, including Anthropic, OpenAI, Google, Ollama, and OpenRouter	Provider API key, or ACP sign-in through some existing subscriptions	Start with low-privilege extensions and a sandbox; do not connect production data	AAIF’s open-source local agent, with CLI, desktop, and API	docs · repo
	Aider	People who want to manage code changes with git diff / commit	Multiple cloud APIs, OpenRouter, OpenAI-compatible endpoints, and local models	Provider API key, config file, or environment variable	Start in a clean demo repo; note Aider’s git auto-commit behavior	Open-source terminal pair-programming tool; official docs specify its git integration	docs · repo
	Pi	People who want to start from a small core and extend it with extensions, skills, or RPC	Subscription providers, API-key providers, custom providers; can connect to a local endpoint	`/login` or a provider API key	Pi has no built-in sandbox; use a disposable repo or container and review commands manually	An extensible minimal terminal coding harness	provider · repo
	Hermes Agent	People who want to use the same agent in a terminal, desktop app, or chat platform	Nous Portal, OpenRouter, Anthropic, Google, and other providers	Set an API key or OAuth with `hermes model`; Nous Portal supports OAuth	Start in a low-risk repo; enable skills, MCP, and provider permissions one at a time	Nous Research’s open-source agent; docs provide CLI and multi-interface integrations	provider · repo

Where do OpenRouter and Ollama fit?¶

OpenRouter is a Router, so it is not one of the 9 coding CLIs above; it provides a unified API, provider routing, and centralized usage. Ollama is a local runtime, not an agent; it can provide a compatible API at http://localhost:11434/v1 for OpenCode, goose, Aider, or another client. Neither replaces an agent’s file permissions and sandbox design.

Keep four things when moving a prompt between CLIs¶

Write down the file paths, allowed scope, and the order “list a plan first, then change after confirmation.”
Record the model, provider, API key, and approval / sandbox settings separately; do not assume they stay the same when you change CLIs.
Describe the goal in ordinary language; use slash commands such as /login and /permissions only in the relevant tool’s section.
Ask for git diff, test results, and unfinished items, and restore the worktree before using another CLI.

Expand rules files, sandbox, and common questions

Claude Code’s project rules are in CLAUDE.md; Codex uses AGENTS.md. OpenCode gives AGENTS.md priority and uses CLAUDE.md as a compatibility fallback when it is absent; do not treat a nonexistent OPENCODE.md as a common format.
Gemini CLI’s project context and .gemini/ settings follow its official docs; --sandbox, approval mode, and --yolo have different risks, so do not skip confirmation on your first try.
Pi’s project trust is not a sandbox. Its official safety docs explicitly warn that it runs with the permissions of the user who starts it; use a container or another OS-level boundary when isolation is needed.
Aider’s official docs explain git integration and auto-commit after editing; start in a clean demo repo, inspect the commit, then bring it into a working repo.
For goose, Hermes Agent, and other agents that can connect MCP / extensions, start with a low-privilege, read-only integration; do not use Gmail, Slack, or a production DB as your first external connection.
Put API keys only in an officially supported credential store or environment variable; never put them in a repo, prompt, screenshot, or issue. Calculate cost from the day’s official price and actual usage, not from the model name.

Official verification entry points (2026-08-30 UTC)¶

Return to Track A¶

For your first safe operation, return to A1.
To fix rules files and repeatable workflows in place, go to A2.
To work on MCP, CI, and usage traces, go to A3.

Maintenance principle: tools, sign-in, pricing, sandbox, and providers change. Recheck official docs and update the checked-on date before editing the table. Keep this table factual; do not maintain popularity or subjective ratings.