1.1 Installation and First Command

📋 Requirements and Installation

🧠 Imagine It This Way: Installing Claude Code is like installing Git for the first time. One command, one authentication, and from then on you have a new superpower in the terminal that you'll never give up.

O Claude Code is a command-line tool (CLI) from Anthropic that puts Claude directly in your terminal. Unlike web chat, here Claude has access to your codebase, it can read and edit files, run commands, and act as a full-fledged development agent.

To install, you need Node.js 18+ (the JavaScript runtime). If you already have Node, installation is a single command. There are three options, depending on your operating system:

installation via npm (any OS)

npm install -g @anthropic-ai/claude-code

npm (universal)

Works on Mac, Linux, and Windows. Requires Node.js 18+ installed. The most common path.

Homebrew (macOS)

brew install claude-code if you use Homebrew on Mac. Manages updates automatically.

winget (Windows)

winget install Anthropic.ClaudeCode on Windows. Integrates with the native package manager.

💡 Tip: Authentication

The first time you run Claude Code, it will ask you to authenticate. You can log in through a browser (recommended) or set the variable ANTHROPIC_API_KEY in your environment. Browser login links your Anthropic account and enables use with Pro/Max/Team plans.

In one sentence: Node.js 18+ and an npm install -g, and you have Claude Code up and running.

▶️ First claude in the terminal

🧠 Imagine It This Way: opening Claude Code for the first time is like turning the ignition on a new car. The engine purrs, the dashboard lights up, and you realize you have an intelligent copilot in the passenger seat.

Open the terminal, navigate to any project folder, and type claude. Done. The interactive interface will appear, showing which model is running and waiting for your prompt. You’re talking directly to Claude, but now it has access to the files in the current directory.

first command

cd ~/meu-projeto
claude

When you start, try asking for something simple: "explain what this project does" or "list the main files". Claude will read the files in the directory and respond with real context. That’s already different from any web chatbot, because it’s within of your project.

one-shot mode (no session)

claude "explain what the package.json file does"

In one sentence: claude in the terminal opens an interactive session with full access to your project.

🔀 Interactive vs. One-Shot Mode

🧠 Imagine It This Way: interactive mode is like sitting at a table with Claude to work together for hours. One-shot mode is like sending a quick note through the window and getting a reply back.

Claude Code has two fundamental modes of use. In interactive mode (just type claude), you open an ongoing conversation. Each message keeps the context of the previous ones, Claude can ask for confirmation before editing files, and you control the flow step by step. It’s the default mode for development.

No one-shot mode (using the flag -p), you send a single prompt, get a response, and the process ends. Ideal for automation, scripts, and quick questions. The flag -p (of "print") field says: run this and return the result to me on stdout.

✓ Interactive Mode

• Conversation continues with context
• Asks for confirmation before edits
• Ideal for development
• Command: claude

→ One-shot mode

• One question, one answer
• Output goes to stdout
• Ideal for scripts and pipes
• Command: claude -p "..."

In one sentence: claude to chat, claude -p to ask and exit.

📖 Navigating --help and Essential Flags

🧠 Imagine It This Way: Claude Code flags are like the buttons on an airplane dashboard. You don’t need to know them all on day one, but the essentials keep you in the air.

The starting point is always claude --help. It lists all available flags with a short explanation. You’ll use only a few in your day-to-day work:

essential flags

claude --help          # ver todas as opções
claude --version       # versão instalada
claude -p "..."        # modo one-shot (print)
claude --resume        # retomar sessão anterior
claude --model opus    # escolher o modelo
claude --verbose       # modo verboso (debug)

--help

Always the first command when you forget something. A complete reference at your fingertips.

-p (print / one-shot)

The most commonly used flag. It turns Claude Code into a Unix pipe tool.

--resume

Resume the previous session. Essential when you accidentally close the terminal.

--model

Chooses which model to use. Opus for complex tasks, Sonnet for quick tasks.

In one sentence: --help is your pocket guide; -p, --resume e --model are the everyday flags.

🔄 Updating and Versioning

🧠 Imagine It This Way: Claude Code evolves quickly. Each new version brings features, improvements, and fixes. Keeping it updated is like keeping your toolbox sharp.

Claude Code gets frequent updates. Checking your version and updating are simple operations:

check and update

claude --version                              # ver versão atual
npm update -g @anthropic-ai/claude-code       # atualizar via npm

Claude Code also notifies you when an update is available at the start of a session. The recommendation is to always keep the latest version, since new features (such as MCP servers, better permissions, and new slash commands) appear frequently. See the changelog official source to find out what changed between versions.

💡 About Breaking Changes

Major changes are rare, but they happen. If you have scripts that depend on Claude Code, test them after updating. The command claude --version at the beginning of scripts helps ensure compatibility.

In one sentence: npm update -g to update; --version to check.

🔧 Diagnosing Common Issues

🧠 Imagine It This Way: like all software, Claude Code can run into installation problems. The good news is that the most common errors have one-line fixes.

If something went wrong during installation or the first run, go through this checklist. It covers 90% of the problems beginners encounter:

✗ Common Errors

• EACCES permission denied with npm install -g
• Node version mismatch (18+ required)
• Authentication failed on the first run
• command not found: claude after install

✓ Solutions

• Use sudo npm install -g or configure npm prefix
• Update Node: nvm install 20
• Run claude and follow the login flow in the browser
• Check whether npm/bin is in PATH

checklist-diagnostico.txt

Claude Code não funciona? Checklist rápido:
[ ] Node.js 18+ instalado?  → node --version
[ ] npm global acessível?   → npm list -g --depth=0
[ ] claude no PATH?         → which claude
[ ] Autenticação ok?        → claude (e siga o login)
[ ] Versão atualizada?      → claude --version
Se 3+ falharam, reinstale: npm uninstall -g @anthropic-ai/claude-code && npm install -g @anthropic-ai/claude-code

In one sentence: Node, npm, PATH, and auth: resolve these four and Claude Code works.

🧾 Module Summary

✓

Install with 1 command — npm install -g @anthropic-ai/claude-code (requires Node 18+).

✓

Two modes of use — interactive (claude) for development, one-shot (claude -p) for scripts.

✓

Essential flags — --help, -p, --resume, --model, and --version cover day-to-day use.

✓

Troubleshooting — Node + npm + PATH + auth = the 4 diagnostic checkpoints.

Next module:

1.2 — Navigating the CLI Like a Pro: shortcuts, slash commands, sessions, and pipes.

← Back to Track Next Module →