A1 — Choose a CLI agent and safely complete your first small task¶

CLI (Command-Line Interface): an interface operated by typed terminal commands.

← Back to the main path README · Track A: CLI Power User — Stop 1 · Next: A2

This stop explains what “AI in the terminal” means, then has you run it once in a disposable demo repo (a Git-managed practice project folder). You will first have the tool read files, find the test command, and propose a plan; only after you confirm the plan will it make a small change that you can inspect with git diff and undo.

If you want to use existing tools to get work done and do not want to write agent programs yet, this is your entry point.

Do only this for now¶

Prepare a disposable demo repo with no secrets. If you have not installed a tool yet, choose one in the short table below, follow its official entry point to install and sign in, then copy this request directly:

Read the current demo repo only, explain its purpose, find the test command, and propose a small documentation-change plan. Do not modify or delete files yet, and do not run commands that change data.

When it is done, you should see a repo summary, a test command, a plan waiting for confirmation, and a permission prompt when the tool requests access. That is the first verifiable result of this track.

📌 Learning Goals¶

Distinguish an LLM (Large Language Model, a model that reads and writes language), Provider API (Application Programming Interface, an interface through which programs request a service), Router, Coding agent, and Local runtime.
Choose an entry point based on the account, provider, or local environment you already have; do not make an overall ranking.
Complete one “read first → inspect the plan → confirm → small change → git diff → undo” cycle in a demo repo.

Expand time, prerequisites, account, and cost

Time: The first read-only pass and plan review can usually be completed in one short session; you can spread CLI-1 through CLI-4 over several days rather than doing them all at once.
Prerequisites: You can enter a folder and inspect git status and git diff; you have a disposable demo repo on hand.
Account: Prepare a sign-in method supported by the tool you choose, or connect the agent to a local model runtime. If you have no account, start with the selection table and the official Quickstart below.
Cost: Do not guess. Check the day’s official pricing / usage page before you start; this exercise has no model API charge only when the entire flow stays local.

🧩 Five Core Terms First¶

Core term	What it is, in plain language	How A1 uses it	What it is not
LLM (Large Language Model)	The model that generates text or code, like the brain that thinks of answers in a workbench	Claude, GPT, and Gemini are model families	It does not manage the repo, file permissions, or billing
Provider API (model-service entry point)	The door that lets a tool send a request to one model service	Anthropic, OpenAI, and Gemini APIs handle authentication and billing	It is not a coding agent that edits files
Router	A transfer station that sends the same request to different providers	OpenRouter can centralize API, routing, and usage	It is not an LLM and does not manage file permissions
Coding agent (coding workbench)	A workbench that can read files, edit files, and run commands in the terminal	Claude Code, Codex, OpenCode, and Pi are in this group	Its model, provider, and sandbox still need separate checks
Local runtime (local model engine)	An engine that runs a model on your own computer, like a motor starting the model	Ollama lets compatible agents call a local model	It is not a coding agent and does not read a repo by itself

Choose an entry point from what you already have¶

What you already have	Entry points to check first	Confirm first
An Anthropic account or API	Claude Code	Sign-in and permission prompts
ChatGPT or an OpenAI API	Codex CLI	Approval, sandbox, and working directory
A Google account, API, or Vertex AI	Gemini CLI	Authentication and sandbox
You want to switch providers or use a local model	OpenCode, goose, Aider, or Pi	Provider and permission boundaries
You want a Router or local runtime	OpenRouter or Ollama	They must be paired with a coding agent

📚 Required Reading¶

Claude Code Quickstart and permissions
Codex CLI
Gemini CLI authentication and sandbox configuration
OpenCode docs and goose docs
Aider docs, Hermes Agent docs, Grok Build repo, and Pi docs
OpenRouter FAQ and Ollama

The per-request cost and total cost for this track’s cloud requests vary with your account, provider, model, input and output tokens, and subscription quota; check the day’s official pricing or usage page before practicing. Only when both the agent and provider are configured to connect solely to local Ollama, with no other cloud service called, will this exercise have no model API charge; file and command permissions still need the usual checks.

🛠 Hands-on Exercises¶

Hands-on CLI-1: Read the demo repo first, then make one reversible small change¶

Outcome: You can see the repo description, test command, and a plan waiting for confirmation; after confirming, you leave one small change that can be checked with git diff.

Expand CLI-1 preparation, operation, and undo steps

Create or copy a disposable demo repo. Include only a README, a small amount of source code, and tests; do not include API keys, personal data, contracts, or production settings. Before you start, run git status --short and confirm that no one else has unfinished changes.
Use the “read only” request above first. Compare the files, test command, and plan the tool lists; ask about anything unclear instead of approving it immediately.
After you confirm the plan, allow only one small documentation change, such as adding “How to run the tests” to README.md. Ask the tool to show the diff first, then approve it.
Run git diff -- README.md in the terminal and confirm that it contains only the expected content. Run git restore -- README.md only if Step 1 confirmed that the file was clean originally; then run git status --short again to confirm that the small change is undone.

If the tool does not have git, keep an original-file backup and compare line by line; do not give the same demo repo to two agents that can write files at the same time.

Hands-on CLI-2: Make sure the project rules are read correctly¶

Outcome: You can use a short rules file to state the project purpose, prohibitions, test command, and delivery format, then verify that the tool followed it.

Expand project-rule locations and verification for each CLI

Claude Code reads the project’s CLAUDE.md; Codex uses AGENTS.md.
OpenCode gives AGENTS.md priority; CLAUDE.md is a compatibility fallback when AGENTS.md is absent. Do not create OPENCODE.md as a general rules file.
Gemini CLI commonly uses GEMINI.md; goose, Aider, Hermes Agent, Pi, and Grok Build use filenames and loading scopes set by their respective official docs.
Keep rules limited to content that changes behavior: project purpose, things it must not do, the test command, and the delivery format. Do not put a long API reference into a rules file that loads every time.

Add one observable rule in the demo repo, such as “propose a plan first; do not modify data/,” then send a request that triggers it. Finally, inspect the agent’s response and git diff.

Hands-on CLI-3: Run the same request again with a second harness¶

Outcome: You can record differences between two tools in model / provider, permission prompts, sandbox, and output format instead of choosing a winner by subjective score.

Expand the fair-comparison steps for a second CLI

Run each tool once in the same clean demo repo with the same prompt and same set of files. Record the date, CLI version, LLM, provider, sign-in method, approval / sandbox settings, whether it actually changed files, and the git diff result. Do not start two sessions that can write at the same time; undo the changes after each run before starting the next one.

Hands-on CLI-4: Observe authentication failure with fake credentials¶

Outcome: You can distinguish “sign-in failed,” “provider API key failed,” “model name does not exist,” and “permission / sandbox blocked,” without putting a real secret into a prompt or log.

Expand the safe authentication-error experiment

In a one-time terminal session, use a value clearly marked as fake, such as not-a-real-key; do not change a production shell configuration or shared .env. First observe the not-signed-in error; then, in a signed-in CLI, enter an officially nonexistent model name and record the error type and recovery guidance. Clear the fake value immediately after testing, and confirm that the shell history, working directory, and logs contain no real key.

Requests using valid credentials may incur charges; for the first exercise, you can use local Ollama or a provider’s explicitly free quota, based on that day’s official pricing and actual usage.

🎯 Curated Projects¶

A1 teaches you how to start safely; it does not maintain the same fast-changing data in two pages. Sign-in, provider, sandbox, and official sources for the 9 tools are centralized in the CLI Agents reference guide. Official data checked on: 2026-08-30 UTC.

Editorial ratings are learning-map guidance, not GitHub stars or an overall ranking. ⭐⭐⭐⭐⭐ means read this first when you choose that tool path; it does not mean install every five-star tool.

Category	Project	Rating	Best for	Watch first
Official model ecosystems	anthropics/claude-code	⭐⭐⭐⭐⭐	People using the Anthropic ecosystem	Keep the permission prompt; start in a demo repo
	openai/codex	⭐⭐⭐⭐⭐	People with ChatGPT or an OpenAI API	Confirm approval, sandbox, and working directory
	google-gemini/gemini-cli	⭐⭐⭐⭐	People with Google auth or Vertex AI	Confirm authentication and sandbox first
	xai-org/grok-build	⭐⭐⭐	People trying the xAI ecosystem or a new tool	Observe in a demo repo; do not make it your first production tool
Provider-flexible	anomalyco/opencode	⭐⭐⭐⭐⭐	People switching providers or using a compatible endpoint	`AGENTS.md` has priority; check permission settings
	aaif-goose/goose	⭐⭐⭐⭐	People using CLI, desktop, and extensions	Start with low-privilege extensions
	Aider-AI/aider	⭐⭐⭐⭐⭐	People who value git diff and commit workflows	Understand its git auto-commit behavior
	earendil-works/pi	⭐⭐⭐⭐	People extending a small core with extensions, skills, or RPC	No built-in sandbox; use a container or VM when isolation is needed
	NousResearch/hermes-agent	⭐⭐⭐⭐⭐	People using one agent in terminal, desktop, or chat	Enable provider, Skill, and MCP permissions one at a time
Router / local engine	OpenRouter	⭐⭐⭐⭐	People switching providers through one API	It is a Router and still needs an agent
Router / local engine	ollama/ollama	⭐⭐⭐⭐⭐	People running models on their own computer	It is a local runtime and still needs an agent

Expand the shortest way to distinguish “tool, Router, and local runtime”

Claude Code, Codex, Gemini CLI, OpenCode, goose, Aider, Hermes Agent, Grok Build, and Pi: CLI agents / harnesses that receive tasks and operate in the working directory.
OpenRouter: a Router that sends an agent’s request to a provider; it does not manage your file permissions.
Ollama: a runtime for running models locally; it does not read a repo by itself and must be called by an agent that supports it.
When unsure, ask only three questions: Who runs the model? Who forwards the request? Who can read and write my files?

✅ Self-check before A2¶

I can explain the five identities in my own words and know that OpenRouter is not an LLM and Ollama is not a coding agent.
In a demo repo, I completed a read-only explanation and plan without giving the tool any secrets.
I checked the diff for one small change and can undo it.
I know the selected CLI’s sign-in method, provider, and approval / sandbox settings.

After that, continue to A2 — Build a reusable CLI workflow. To compare the tools’ official status again, return to resources/cli-agents-guide.en.md.

Safety baseline: do not run your first experiment in a directory containing secrets or production permissions; do not use a mode that skips all confirmations; do not paste API keys, browser tokens, or auth files into prompts, issues, logs, or git.