SU8 Codes
< Back to blog
Official article Updated 7 min read

Claude Code Tutorial: From Install to Your First Code Change

Install Claude Code, sign in, run your first prompt and code change, learn the daily commands, and connect a third-party API gateway. Install steps tested on 2.1.323.

#claude-code#tutorial
Claude Code Tutorial: From Install to Your First Code Change

Claude Code is Anthropic's coding agent for the terminal. You give it a task in plain language and it reads your project, edits files, and works with Git. This tutorial covers installing it, signing in, a first prompt and a first edit, the commands you'll use daily, and pointing it at a third-party API gateway. To compare it with Codex CLI, Cline, and others first, see how the main AI coding agents compare.

What was tested: the install and claude doctor steps were run on Claude Code 2.1.323 in November 2026. Sign-in, prompting and editing follow the official docs as of that date and weren't run end to end.

Requirements

From the setup docs:

ItemRequirement
macOS13.0+
WindowsWindows 10 1809+ or Windows Server 2019+
LinuxUbuntu 20.04+, Debian 10+, Alpine 3.19+
RAM4 GB+
CPUx64 or ARM64
ShellBash, Zsh, PowerShell, or CMD
LocationAnthropic supported countries

You also need one of the following: a paid Claude plan (Pro, Max, Ultra, Team, or Enterprise), a Console account with prepaid credits, or a cloud provider such as Bedrock, Vertex, or Foundry. The free claude.ai plan doesn't include Claude Code. If none of those fit, see the gateway section below.

Install Claude Code

PATH fixes, the 403 error, and choosing between install methods are covered in How to Install Claude Code.

On macOS, Linux, or WSL:

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

On Windows, in PowerShell (not tested for this tutorial):

irm https://claude.ai/install.ps1 | iex

Open a new terminal and check it:

claude --version

You should see something like 2.1.323 (Claude Code). If the shell can't find claude, the install directory isn't on your PATH yet; see the PATH fix.

For a fuller read-only check:

claude doctor

In a fresh-home test on macOS 26.5.2 (Apple Silicon), the installer finished in about 34 seconds. claude doctor then showed Running: native (2.1.323), Search: OK (bundled) and Auto-update channel: latest.

Other install methods

  • Homebrew: brew install --cask claude-code. This installs the stable channel, which typically trails the latest release by about a week. It doesn't auto-update, so run brew upgrade claude-code yourself.
  • WinGet: winget install Anthropic.ClaudeCode. Upgrade with winget upgrade Anthropic.ClaudeCode.
  • npm: npm install -g @anthropic-ai/claude-code@latest. It requires Node.js 22+. Don't use sudo. To upgrade, rerun the same command rather than npm update -g.

Native installs (the curl and PowerShell scripts) update themselves in the background. Run claude update to update right away.

"syntax error near unexpected token '<'"

The installer can print this when the request is redirected to an HTML page instead of the script. In a test it happened on a server outside Anthropic's supported regions: install.sh redirected to an "app unavailable in region" page. Check the location requirement above.

Sign in

cd /path/to/your/project
claude

The first launch opens a browser to log in. If ANTHROPIC_API_KEY is set in your environment and you approve it when asked, Claude Code uses that key and skips the browser.

Type /status in a session to see which credential is active (Auth token or API key). If you've configured a gateway, /status also shows an Anthropic base URL line.

Your first prompt and first edit

The quickstart suggests starting with:

what does this project do?

Other starter questions from the same page: where is the main entry point?, explain the folder structure, what technologies does this project use?.

Then ask for a small change:

add a hello world function to the main file

Approve the edit when prompted. Shift+Tab cycles through permission modes; the permission modes page explains each one.

Claude Code commands for daily use

CommandWhat it does
claudeStart an interactive session
claude "task"Start a session with a first prompt
claude -p "query"Answer once and exit
claude -cContinue the most recent conversation
claude -rPick an earlier conversation to resume

Inside a session:

  • /clear starts a fresh conversation (/resume brings the old one back).
  • /help lists commands.
  • /exit quits; pressing Ctrl+D twice also quits.
  • Typing / shows available commands, Tab completes them, and ↑ recalls history.

The quickstart's advice for new users:

  • Be specific.
  • Break larger tasks into steps.
  • Let Claude read the relevant code before it edits.

For Git, ask directly. The docs' examples are what files have I changed?, commit my changes with a descriptive message and create a new branch called feature/quickstart.

Use a third-party gateway

Claude Code can send model requests to any gateway that serves a format it supports. Per the gateway connection docs, you set two things:

  • ANTHROPIC_BASE_URL: the gateway's address.

  • A credential, in one of two variables:

    • ANTHROPIC_AUTH_TOKEN, sent as Authorization: Bearer;
    • ANTHROPIC_API_KEY, sent as x-api-key.

    If you don't know which header the gateway reads, start with ANTHROPIC_AUTH_TOKEN and switch if you get a 401.

Put them in the env block of ~/.claude/settings.json to apply everywhere, or .claude/settings.local.json for one project. Keep credentials out of any .claude/settings.json you commit.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example",
    "ANTHROPIC_AUTH_TOKEN": "your-credential"
  }
}

To check the connection, export the two variables in your shell and run the one-token request from the gateway connection docs:

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

What the result means:

  • A JSON reply starting with {"id":"msg_: the URL and credential both work.
  • An "unknown model" error: the URL and credential still work.
  • A 401: the credential was rejected. Try the other variable.

Example: SU8 Codes, the API relay that publishes this blog, has a Claude Code setup page. As of November 2026 it sets:

  • ANTHROPIC_BASE_URL to https://www.su8.codes;
  • ANTHROPIC_AUTH_TOKEN to your SU8 key;
  • the model variables to the model you want (see the model list).

After filling those in, verify with the curl above or with /status.

Errors seen in a test against the SU8 endpoint with a deliberately invalid key (Claude Code 2.1.323):

  • claude -p failed with Failed to authenticate. API Error: 401 unauthorized. That's a credential problem.
  • With a model name the gateway defines, you'll also see a [claude-code:unrecognized_model] warning. It means the name isn't in Claude Code's built-in model list. In this test the request had already failed with the 401 above, so whether a run with a valid key continues past this warning wasn't checked.

Troubleshooting

Startup warns about two credential sources. A saved login and a gateway credential are both active. To use the gateway, run /logout. To use your subscription, unset the variable.

API returned an empty or malformed response (HTTP 200). The gateway, or a proxy in front of it, answered with something that isn't an API response, often an HTML error or login page. Run the curl check to find which hop is returning HTML.

Changes to settings don't seem to apply. Fully quit and restart Claude Code after editing the config, as the setup page in the example above says, then confirm the base URL and credential source with /status.

FAQ

Is Claude Code free?

No. You need a paid Claude plan (Pro, Max, Ultra, Team, or Enterprise), a Console account with prepaid credits, or a cloud provider such as Bedrock, Vertex, or Foundry. The free claude.ai plan doesn't include Claude Code.

How do I install Claude Code on Windows?

Run irm https://claude.ai/install.ps1 | iex in PowerShell, or winget install Anthropic.ClaudeCode. It needs Windows 10 1809+ or Windows Server 2019+. Windows wasn't tested for this tutorial.

Does Claude Code update itself?

Native installs (the curl and PowerShell scripts) update in the background, and claude update updates right away. Homebrew installs don't auto-update: run brew upgrade claude-code. For WinGet, upgrade with winget upgrade Anthropic.ClaudeCode.