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 tool facts below are visible. Record the “checked on” date alongside your installed version. Official data checked on: 2026-08-30 UTC.

Stable channels and a scoped check (2026-10-11 UTC): Use an official stable release as the beginner baseline. Use alpha, preview, or nightly only to test a specific capability in an isolated demo repo; read release notes, pin the exact version, and keep a rollback path. The official release pages mark Codex CLI 0.163.0-alpha.5 and Gemini CLI 0.65.0-nightly.20261010.g9b6e0265d as pre-releases, so neither is a stable beginner baseline. This checks only release-channel labels; the full table’s last complete check remains 2026-08-30 UTC.

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

More about OpenRouter and Ollama

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

1. Write down the file paths, allowed scope, and the order “list a plan first, then change after confirmation.”
2. Record the model, provider, API key, and approval / sandbox settings separately; do not assume they stay the same when you change CLIs.
3. Describe the goal in ordinary language; use slash commands such as /login and /permissions only in the relevant tool’s section.
4. 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)

• Claude Code overview · permissions
• OpenAI Codex CLI
• OpenCode · canonical repository
• Gemini CLI
• goose · canonical repository
• Aider
• Hermes Agent
• Grok Build
• Pi · canonical repository
• OpenRouter FAQ · Ollama

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.