12 Installing a CLI agent

13 Installing a CLI agent

A CLI agent is the third harness from Chapter 0f — a tool you start in a project folder, that reads, writes, and runs files in that folder, and that you talk to in plain English. This book uses Claude Code as the default. The principles transfer to any of the alternatives.

13.1 What you will get from this chapter

Claude Code installed and running in a project folder.
A first session where it can see your files.
A note on permissions — what to grant, what to refuse.

13.2 Before you install

Two things should already be in place from earlier in Part 0:

A working terminal — see Chapter 0g.
An AI account with API or paid-plan access — see Chapter 0e. For Claude Code, you need a Claude Pro / Max subscription, or a Claude Console account with credits. The free tier of Claude.ai does not give you the CLI.

If both are in place, the install is a one-liner.

13.3 Install Claude Code

The current install commands are at docs.anthropic.com/claude-code. They look like this on the day this chapter was written:

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

Verify it worked:

claude --version

You should see a version number. If you see “command not found,” close the terminal, open a new one, and try again — installers add claude to your PATH, but only new terminals see the change.

13.4 First session

Navigate to a project folder — any folder with a few real files in it.

cd ~/Documents/dawai-scratch
claude

A welcome message appears. The first time, it sends you to a browser to log in. After that, you are in a chat — but a chat that can see every file in this folder.

Try a small request:

“List the files in this folder. Tell me, in two sentences, what each of them appears to be.”

Claude Code reads them and answers. That is the harness: the AI is no longer guessing what your files contain. It is looking.

13.5 A note on alternatives

The other CLI agents work the same way; only the install command and the model behind them differ.

Codex CLI (OpenAI). Install via npm install -g @openai/codex. Requires a paid ChatGPT plan or an API key.
Aider (open-source, model-agnostic). pip install aider-chat. Works with Claude, ChatGPT, or local models.
Cursor agent mode. Inside the Cursor IDE rather than a CLI, but the workflow is the same.

The chapters that use a CLI agent are written so the actions transfer. Where Claude Code does something specific that matters — CLAUDE.md files, skills, headless mode — the chapter says so and the same idea has equivalents in the alternatives.

13.6 Permissions: what to grant

A CLI agent will ask you, the first time, whether to grant permissions to read files, edit files, run commands, and access the network. The defaults are reasonable. A few habits make them safer.

Start permissive on a fresh folder. If the folder has nothing precious in it, let the agent do what it needs to do. You will learn faster.
Tighten on a real project. When the folder contains analysis you care about, switch to a mode where the agent asks before it writes or runs. Most CLI agents have this as a flag or a setting.
Always review what it changed. git status and git diff after a session show you exactly what touched the project. This is non-negotiable.
Never let it touch credentials. If a folder contains an .env file with API keys, exclude it from the agent’s access (most tools have a .gitignore-like mechanism).

13.7 A first real task

Try this in the same scratch folder:

“Create a small Python script called summary.py that reads any CSV in this folder, prints its dimensions, and prints the first five rows. Test it on <one-of-your-csvs>.”

The agent will:

Write summary.py.
Run it.
Show you the output.
Likely fix one small thing if it errored.

Watch the whole loop. That is what the CLI harness gives you that the others do not.

13.8 Where AI helps · Where AI bluffs

Helps. End-to-end tasks across multiple files. Diagnosing what your project does when you have not opened it in months. Refactoring with an actual run-test loop instead of guesses.

Bluffs. Confidently running a command that does the wrong thing. Producing a long, plausible explanation of what it just did when, in fact, it failed silently. Generating files that look correct and that, on inspection, are missing the substance you asked for. The fix is the same in every case: check the diff, run the script yourself, look at the output.

13.9 Keep this with you, not the AI

Permissions. Grant deliberately, especially on real projects.
Scope of a session. “Do this one thing” is safer than “do all of this.” A one-off agent that finishes quickly is easier to audit.
The decision to keep the changes. git restore . is your friend if the session went badly. Use it without guilt.

13.10 Try this

In a fresh folder, run git init, drop in any small CSV, start Claude Code, and ask: “Print the row count and column names of every CSV in this folder.” Watch what it does. Run git status after — there should be nothing modified, because you only asked it to read. Total time: under five minutes.

13.11 AI and me

How did AI support me here?
How did AI fail me?
How did AI extend me?

13.12 Where to go next

You are done with Part 0. Chapter 1 — AI for coding work is the start of Part I. We get out of setup and into the substance.

--- title: "Installing a CLI agent" --- # Installing a CLI agent A CLI agent is the third harness from [Chapter 0f](00f-three-harnesses.qmd) — a tool you start in a project folder, that reads, writes, and runs files in that folder, and that you talk to in plain English. This book uses **Claude Code** as the default. The principles transfer to any of the alternatives. ## What you will get from this chapter - Claude Code installed and running in a project folder. - A first session where it can see your files. - A note on permissions — what to grant, what to refuse. ## Before you install Two things should already be in place from earlier in Part 0: - A working **terminal** — see [Chapter 0g](11-terminal-basics.qmd). - An **AI account** with API or paid-plan access — see [Chapter 0e](00e-ai-account.qmd). For Claude Code, you need a Claude Pro / Max subscription, or a Claude Console account with credits. The free tier of Claude.ai does not give you the CLI. If both are in place, the install is a one-liner. ## Install Claude Code The current install commands are at [docs.anthropic.com/claude-code](https://docs.anthropic.com/en/docs/claude-code/quickstart). They look like this on the day this chapter was written: ``` # macOS / Linux curl -fsSL https://claude.ai/install.sh | bash # Windows (PowerShell) irm https://claude.ai/install.ps1 | iex ``` Verify it worked: ``` claude --version ``` You should see a version number. If you see *"command not found,"* close the terminal, open a new one, and try again — installers add `claude` to your PATH, but only new terminals see the change. ## First session Navigate to a project folder — any folder with a few real files in it. ``` cd ~/Documents/dawai-scratch claude ``` A welcome message appears. The first time, it sends you to a browser to log in. After that, you are in a chat — but a chat that can see every file in this folder. Try a small request: > *"List the files in this folder. Tell me, in two sentences, what each of them appears to be."* Claude Code reads them and answers. *That is the harness:* the AI is no longer guessing what your files contain. It is looking. ## A note on alternatives The other CLI agents work the same way; only the install command and the model behind them differ. - **Codex CLI** (OpenAI). Install via `npm install -g @openai/codex`. Requires a paid ChatGPT plan or an API key. - **Aider** (open-source, model-agnostic). `pip install aider-chat`. Works with Claude, ChatGPT, or local models. - **Cursor agent mode**. Inside the Cursor IDE rather than a CLI, but the workflow is the same. The chapters that use a CLI agent are written so the actions transfer. Where Claude Code does something specific that matters — `CLAUDE.md` files, skills, headless mode — the chapter says so and the same idea has equivalents in the alternatives. ## Permissions: what to grant A CLI agent will ask you, the first time, whether to grant permissions to read files, edit files, run commands, and access the network. The defaults are reasonable. A few habits make them safer. - **Start permissive on a fresh folder.** If the folder has nothing precious in it, let the agent do what it needs to do. You will learn faster. - **Tighten on a real project.** When the folder contains analysis you care about, switch to a mode where the agent asks before it writes or runs. Most CLI agents have this as a flag or a setting. - **Always review what it changed.** `git status` and `git diff` after a session show you exactly what touched the project. This is non-negotiable. - **Never let it touch credentials.** If a folder contains an `.env` file with API keys, exclude it from the agent's access (most tools have a `.gitignore`-like mechanism). ## A first real task Try this in the same scratch folder: > *"Create a small Python script called `summary.py` that reads any CSV in this folder, prints its dimensions, and prints the first five rows. Test it on `<one-of-your-csvs>`."* The agent will: 1. Write `summary.py`. 2. Run it. 3. Show you the output. 4. Likely fix one small thing if it errored. Watch the whole loop. *That* is what the CLI harness gives you that the others do not. ## Where AI helps · Where AI bluffs **Helps.** End-to-end tasks across multiple files. Diagnosing what your project does when you have not opened it in months. Refactoring with an actual run-test loop instead of guesses. **Bluffs.** Confidently running a command that does the wrong thing. Producing a long, plausible explanation of what it just did when, in fact, it failed silently. Generating files that look correct and that, on inspection, are missing the substance you asked for. The fix is the same in every case: *check the diff, run the script yourself, look at the output*. ## Keep this with you, not the AI - *Permissions.* Grant deliberately, especially on real projects. - *Scope of a session.* "Do this one thing" is safer than "do all of this." A one-off agent that finishes quickly is easier to audit. - *The decision to keep the changes.* `git restore .` is your friend if the session went badly. Use it without guilt. ## Try this In a fresh folder, run `git init`, drop in any small CSV, start Claude Code, and ask: *"Print the row count and column names of every CSV in this folder."* Watch what it does. Run `git status` after — there should be nothing modified, because you only asked it to read. Total time: under five minutes. ## AI and me 1. How did AI **support** me here? 2. How did AI **fail** me? 3. How did AI **extend** me? ## Where to go next You are done with Part 0. [Chapter 1 — AI for coding work](01-ai-for-coding.qmd) is the start of Part I. We get out of setup and into the substance.