Claude Code CLI Documentation — What the Official Docs Cover, What They Miss, and What I Actually Use Daily

Claude Code CLI Documentation — A Working Developer's Read

---

Table of Contents

• How I Use Claude Code (Real Setup)
• What the Official Docs Cover Well
• Five Documentation Gaps I Hit This Week
• Anatomy of ~/.claude/ — The Map the Docs Don't Draw
• Docs vs Real Usage — Honest Comparison
• Five-Step Path From Quickstart to Daily Use
• FAQ

---

How I Use Claude Code (Real Setup)

I'm Jim, a solo developer in Sydney running five sites on Cloudflare Workers + a couple of Postgres VPSes. Claude Code is the CLI I have open in a terminal pane every working day. The setup: claude-code on macOS (M2 MacBook Pro, fish shell) plus the same binary on a Hostinger Ubuntu VPS for production-side scripts. Both authenticated with the same Anthropic account.

I don't use the desktop app. The whole point for me is the CLI binding to a real shell so the agent reads the same files git does.

This week I deliberately closed every browser tab pointing at the docs and worked from claude code --help plus what I had in ~/.claude/. The five gaps below are the ones that made me reopen the docs — and discover the docs didn't have the answer.

What the Official Docs Cover Well

Credit where it's due. The Anthropic docs at code.claude.com/docs/en/ nail the following:

• Installation and authentication. The npm install, the claude auth login flow, the API key vs subscription distinction — clean.
• The CLI flag reference. --print, --continue, --resume, --allowedTools, --mcp-config — accurate and updated within a couple of weeks of new flags.
• Costs and rate limits. The /docs/en/costs page is honest about session limits and how the Pro / Max plans work.
• The first conversation. Quickstart actually walks through doing something, not just configuring something.

If you're at zero, the docs get you to your first useful conversation in fifteen minutes. That's a real bar and they clear it.

Five Documentation Gaps I Hit This Week

Gap one — Tuesday: slash command argument parsing. I wanted a /deploy <site> command that takes a site slug and runs the right wrangler command. The docs show that slash commands live in ~/.claude/commands/*.md and accept $ARGUMENTS, but they don't say how to parse multiple positional args. I had to read another developer's repo on GitHub to find out you split $ARGUMENTS yourself with shell tooling — there's no built-in $1 $2. Cost me roughly twenty minutes. The fix: I now use read -r site rest <<< "$ARGUMENTS" in the command body.

Gap two — Wednesday: hook exit code semantics. I wired a PreToolUse hook to block git push --force. The docs say "non-zero exit code blocks the tool call." What they don't say: exit code 2 is the one that surfaces the hook's stderr to the model so the model understands why it was blocked. Exit code 1 just kills the tool with a generic error and Claude tries something else. I burned fifteen minutes wondering why my "no force-push to main" warning never reached the agent until I diffed against another working hook.

Gap three — Wednesday afternoon: MCP server lifecycle on shell restart. I have a custom MCP server for the OpenAI Tools Hub Postgres database. After a fresh terminal session, claude code sometimes spawned the MCP server twice. The docs describe how to register an MCP server in .mcp.json but say nothing about how the lifecycle works across sessions or how to detect a stale process. The honest answer (from a GitHub issue): the CLI doesn't reuse a long-running server across sessions, each session starts its own. If you see two it usually means a dangling process from a previous crash. The fix: pkill -f "node my-mcp-server" before each session, or trap EXIT in your launcher.

Gap four — Thursday: skills frontmatter that actually loads. Skills are a newer feature and the docs at /docs/en/skills describe the YAML frontmatter (name, description). What they undersell is how strict the loader is. A trailing space on the name field, a smart quote instead of a straight quote, or a tags field with the wrong shape silently drops the skill — no warning, just absence. I lost an hour on a skill that wouldn't load until I copied a known-good skill's frontmatter byte-for-byte.

Gap five — Friday: how output styles interact with CLAUDE.md. Output styles (~/.claude/output-styles/*.md) and project-local CLAUDE.md files both inject system context. The docs cover each separately. Nowhere is the precedence written down. By trial: the project CLAUDE.md wins when both contain conflicting rules, but the output style still affects formatting (length, headers). If you want a strict "one-line answers" output style to override a project rule that says "always show TODO summaries," you can't — the project file wins on substance, the style only affects shape.

Anatomy of ~/.claude/ — The Map the Docs Don't Draw

After a few months of daily use, here's the directory I actually have. The docs describe each subdir in its own page; nobody draws the whole tree.

Path	What lives there	Loaded when
~/.claude/settings.json	Permissions, hooks, MCP configs (user-level)	Every session
~/.claude/CLAUDE.md	Personal global rules	Every session
~/.claude/commands/*.md	Personal slash commands	On /<name>
~/.claude/skills/<name>/SKILL.md	Personal skills (auto-invoked when relevant)	When the model judges them relevant
~/.claude/output-styles/*.md	Personal output styling rules	When activated by name
~/.claude/hooks/*.sh (referenced from settings.json)	Pre/Post tool hooks	Around tool calls
./.claude/ in any project	Same shape, project-scoped, overlays user-level	When CWD is inside the project
./.mcp.json	Project MCP server registry	On session start in that dir
./CLAUDE.md	Project rules — wins over user-level on substance	On session start in that dir

The two rules I wish the docs stated upfront: project files overlay user files (project wins on conflict for substance), and skills are auto-invoked, commands are explicit. The mental model that follows from those two is enough to figure out the rest from the reference docs.

For a deeper read on what to put in commands/ and skills/, my Claude Code skills field guide walks through the ones I actually use.

Docs vs Real Usage — Honest Comparison

Comparison (⚖️): for each surface, where to spend your reading time.

Topic	Official docs depth	Real-world depth needed
Install + first conversation	Excellent	Read the docs, done.
CLI flags reference	Excellent	Read the docs, done.
Slash commands	Surface-level	Read docs + look at one community repo with non-trivial commands.
Hooks	Mentions exit codes, doesn't explain semantics	Read docs + read the source of one working hook.
Skills	Format described, edge cases omitted	Copy a known-good SKILL.md byte-for-byte first time.
MCP	Configuration covered, lifecycle not	Read docs + skim 2–3 GitHub issues about your scenario.
Output styles	What they are, not how they compose	Trial and error in a scratch project.
Costs and limits	Honest and current	Read the docs, done.

I keep both Anthropic's docs and the community extensions writeup open at the same time. They cover different surfaces.

Five-Step Path From Quickstart to Daily Use

Operational guide (🧭):

1. Run through the official quickstart. Don't skip it; the install + auth flow is accurate and quick.
2. Pick one slash command to write yourself. A /git-status that runs git status and summarises is enough. Doing it teaches you that $ARGUMENTS is one string, not a list, and you parse it yourself.
3. Install one MCP server. Anthropic's filesystem MCP is the painless first one. Watch the session log to see when it spawns and dies.
4. Add a ./CLAUDE.md to your main project with three rules. Verify it overrides the matching user-level rule. Now you understand precedence.
5. Adopt one community skill from a public repo, copy the SKILL.md verbatim, change one line, watch it load. After this, the docs make sense as a reference instead of a tutorial.

For the bigger picture of how Claude Code compares to the IDE side of the toolchain, my Claude Code vs Cursor post covers when to reach for which.

FAQ

Where are the official Claude Code CLI docs? code.claude.com/docs/en/ — quickstart, CLI reference, commands, costs, skills, hooks. The reference pages are the ones that stay current.

Are the docs accurate? For installation, authentication, CLI flags, and costs: yes. For the customisation surfaces (commands, hooks, skills, MCP, output styles): accurate but shallow. Plan to supplement with one community resource per surface.

How often do the docs lag new features? About a week, in my experience. New flags hit the binary first, the GitHub release notes second, the website third. If a feature is too new for the website, search the GitHub issues for it.

Where should I look when the official docs don't have my answer? In order: the GitHub issues for anthropics/claude-code, the discussions tab in that repo, and well-curated community guides. Avoid five-month-old YouTube videos — surface area moves too fast.

Can I run the CLI offline? No. Even with a local MCP server doing the work, the agent calls the Anthropic API for each turn. There is no offline model option as of April 2026.

Does claude code work on Windows? Yes, via WSL2 or directly on PowerShell. The docs cover both. WSL2 is the smoother path; PowerShell occasionally has different quoting rules in slash commands that the docs do flag.

---

How I Verified the Doc Coverage

I read the official docs at code.claude.com/docs/en/ on April 25–27, 2026, working back from quickstart to skills to MCP. The five gaps are sourced from my own session notes (April 21–25) — five real moments where I needed something the docs didn't have. The directory anatomy is from find ~/.claude -maxdepth 3 on my own machine plus find ./.claude -maxdepth 3 in three of my projects.

If the docs change after this post is published, this article gets a dateModified stamp and the relevant section updated. No promises about every micro-revision; substantive shifts only.

About the Author

Jim Liu — independent developer in Sydney running OpenAI Tools Hub, LowRiskTradeSmart, and three other niche sites on Cloudflare + Next.js. I write about CLIs I actually pay for and use daily. No sponsored content; if a tool stops being worth the money I update or remove the post.