Install Claude Code: commands for Windows, macOS, and Linux, an API key without a subscription, and payment with MB WAY

Claude Code is installed with one official command per system: on macOS, Linux, and WSL, curl -fsSL https://claude.ai/install.sh | bash; on Windows, in PowerShell, irm https://claude.ai/install.ps1 | iex (in Command Prompt, CMD, the install.cmd line below). There are then two ways to use it. With a subscription, sign in with a Pro, Max, Team, Enterprise, or Console account (those with only Claude.ai's free plan do not have access to Claude Code). Without a subscription, use an API key: set ANTHROPIC_BASE_URL (the domain only, without /v1), ANTHROPIC_AUTH_TOKEN, and four model variables, and confirm with /status. Kunavo credit can be topped up with MB WAY in the euro checkout, starting from US$ 10, with no monthly fee.

Comandos e variáveis verificados a October 3, 2026 na official Claude Code installation documentation e na environment variable documentation; preços e meios de pagamento verificados a October 3, 2026. Portugal consta da list of countries supported by Anthropic (consultada a October 3, 2026), tanto para o Claude.ai como para a API. Este guia existe também em inglês: Install Claude Code.

Before you install

macOS, Linux, and WSL: a single line

In Terminal (on macOS, it is under Applications › Utilities), run:

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

This is the recommended native installation: a standalone program that, according to the official documentation, updates itself in the background. The claude command is located in ~/.local/bin. A terminal that was already open does not yet know about the new PATH, so open a new window before testing. In WSL, the line is exactly the same, executed inside the WSL terminal.

Install on Windows

On Windows there are two lines, and the choice depends only on the window that is open. If the line starts with PS C:\Users\Nome>, you are in PowerShell; if only C:\Users\Nome> appears, without PS, you are in Command Prompt (CMD). You do not need to use “Run as administrator”: the official documentation explicitly says it is unnecessary, contrary to what some guides in Portuguese recommend.

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

:: Linha de Comandos do Windows (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

On Windows, the most common stumbling block is using the wrong window. If PowerShell responds with The token '&&' is not a valid statement separator, it received the CMD line; if CMD responds with 'irm' is not recognized as an internal or external command, it received the PowerShell line. On Portuguese Windows, this second message may appear translated, with the same cause. And pasting the macOS line containing | bash into PowerShell produces an error saying that bash is not recognized. In all three cases, the solution is to use the line corresponding to the window.

O Git for Windows é opcional. Com ele, a ferramenta Bash do Claude Code passa a correr no Git Bash, e o PowerShell continua disponível ao lado; sem ele, todos os comandos correm pelo PowerShell. Quando o Git está instalado numa pasta fora do habitual e o Claude Code não dá com o bash.exe, indica-se o caminho em CLAUDE_CODE_GIT_BASH_PATH, dentro do bloco env de ~/.claude/settings.json; o exemplo da documentação é C:\Program Files\Git\bin\bash.exe.

WSL is therefore an option, not a requirement, contrary to what some guides say. Those who choose WSL run the macOS/Linux line in the WSL terminal and start claude there as well, not from PowerShell or CMD.

Via Homebrew, WinGet, or npm

It also works, with one important difference: according to the official documentation, installations through Homebrew and WinGet do not update themselves. Updates must be performed manually. Signed apt, dnf, and apk repositories are also available for Linux.

# Homebrew
brew install --cask claude-code
brew upgrade claude-code              # não se atualiza sozinho

# WinGet (Windows)
winget install Anthropic.ClaudeCode
winget upgrade Anthropic.ClaudeCode   # não se atualiza sozinho

The npm package requires Node.js 22 or later—not Node.js 18, as some guides still indicate. With an older Node.js version, npm only displays an EBADENGINE warning during installation instead of failing. Never use sudo npm install -g: the official documentation explicitly advises against it. To update, use @latest, not npm update -g.

node -v                                           # tem de ser v22 ou posterior
npm install -g @anthropic-ai/claude-code          # nunca com sudo

# para atualizar mais tarde: com @latest, não com npm update -g
npm install -g @anthropic-ai/claude-code@latest

Confirming the installation

claude --version   # mostra o número da versão, seguido de (Claude Code)
claude doctor      # diagnóstico só de leitura da instalação e das definições, sem abrir sessão

claude doctor does not start a session: it displays the status of the installation and settings files. It is the fastest way to determine whether a problem lies with the installation or the configuration.

Um command not found: claude (ou, no Windows, a indicação de que claude não é um comando conhecido) quer dizer que o terminal não sabe onde o programa ficou. Muitas vezes basta fechar a janela e abrir outra. Se continuar, falta a pasta no PATH: no macOS e no Linux é ~/.local/bin, a acrescentar no ficheiro de arranque da shell (~/.zshrc ou ~/.bashrc); no Windows é %USERPROFILE%\.local\bin; segundo a official troubleshooting, confirma-se e acrescenta-se assim no PowerShell:

# 1. A pasta de instalação já está no PATH?
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Sem resultado? Acrescente-a ao PATH do utilizador e abra uma janela nova
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. Na janela nova: dois caminhos significam duas instalações lado a lado
where.exe claude

If you installed via npm and PowerShell responds with npm.ps1 cannot be loaded because running scripts is disabled on this system, PowerShell's execution policy is blocking npm scripts. Use the native installer or allow local scripts for your user:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

And if Claude Code does not support 32-bit Windows appears, «Windows PowerShell (x86)» was opened. Windows has two PowerShell entries, and the x86 version runs as a 32-bit process; open «Windows PowerShell» without (x86).

First use: subscription or API key

At first launch, you decide how Claude Code is paid for. Reinstallation is not required to switch routes: what matters is whether a key is defined.

Route A — sign in with the subscription

In the project folder, run claude and sign in in the browser. Be careful if ANTHROPIC_API_KEY is already present in the environment: instead of opening the browser, Claude Code asks for one-time approval of that key. If approval is denied, the key is ignored from then on and the question does not reappear, making it seem as though the variable is not being read. To reactivate it: /config → Use custom API key.

Route B — without a subscription, using an API key

ANTHROPIC_BASE_URL is a Claude Code variable designed to route requests through a proxy or gateway. Pointing it to an endpoint compatible with Anthropic's Messages API is therefore a supported configuration, with no plugins or modified versions. The steps:

1. Create a Kunavo account.
2. Top up your balance in Billing, starting at US$ 10 (payment with MB WAY is explained below).
3. At /app/keys, create a key beginning with sk-kn-. It is shown only once, so save it immediately.
4. Define the variables. On macOS and Linux, in ~/.zshrc or ~/.bashrc:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # só o domínio, sem /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

On Windows, to test first in a PowerShell window:

# Vale só para esta janela do PowerShell
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

For permanent use, the best place is the env block in the user settings: ~/.claude/settings.json (on Windows, %USERPROFILE%\.claude\settings.json). There, the values apply to all projects, including background agents; the VS Code extension is the exception (see below). A variable exported in the shell only reaches programs started from that shell: an editor opened from the Dock or Start menu cannot see it. If the file already contains other settings, add only the env block:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Never ponha a chave no .claude/settings.json de um projeto: segundo a official gateway documentation (consultada a October 3, 2026), esse ficheiro entra nos commits e é partilhado com quem clonar o repositório. E atenção à precedência: quando a shell e um ficheiro de definições definem a mesma variável, prevalece o ficheiro de definições. Se uma alteração na shell não surtir efeito, veja primeiro o settings.json.

Those using the VS Code extension should define the variables in claudeCode.environmentVariables, in VS Code's own user settings (command Preferences: Open User Settings (JSON)). According to the gateway documentation, the extension checks credentials in this setting before starting; values from ~/.claude/settings.json reach the Claude Code process, but not that check:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.kunavo.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-kn-..." },
    { "name": "ANTHROPIC_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL", "value": "claude-opus-5-5" },
    { "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "claude-sonnet-5" },
    { "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "claude-haiku-4-5" }
  ]
}

The four model variables and other pitfalls

Each line in the block has its own pitfall:

• Do not include the path in ANTHROPIC_BASE_URL. The /v1/messages path is added by Claude Code itself; an address already ending in /v1 results in /v1/v1/messages, which returns 404.
• ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY: Kunavo accepts both. According to the gateway documentation, ANTHROPIC_AUTH_TOKEN is sent in the Authorization: Bearer header and takes effect immediately; ANTHROPIC_API_KEY is sent in the x-api-key header and, in interactive mode, must be approved once before taking effect (see Route A). That is why this guide uses ANTHROPIC_AUTH_TOKEN.
• The name in ANTHROPIC_MODEL must be exact. Copy it exactly as shown here: claude-sonnet-5.
• Without ANTHROPIC_DEFAULT_SONNET_MODEL and ANTHROPIC_DEFAULT_OPUS_MODEL, the aliases change automatically. Segundo a model configuration documentation (consultada a October 3, 2026), para quem usa a API da Anthropic o alias opus aponta para o Opus 5.5 e o alias sonnet para o Sonnet 5.5, e estes aliases mudam com as novas versões. Fixa-se com o nome completo do modelo ou com variáveis como ANTHROPIC_DEFAULT_OPUS_MODEL. O Kunavo não serve o Sonnet 5.5, e um modelo que não existe devolve 404: sem ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5, falham o /model sonnet, os subagentes com model: sonnet e o passo de execução do opusplan. Já o opus aponta para claude-opus-5-5, que o Kunavo serve, mas só a partir do Claude Code v2.1.280; quem tiver uma versão anterior corre claude update.
• ANTHROPIC_DEFAULT_HAIKU_MODEL also applies to background tasks. According to the documentation, it defines the haiku alias and the model for Claude Code's background functions. With Claude Haiku 4.5, these calls use the cheapest model in the table below.

Preços por milhão de tokens, do catálogo do Kunavo; a coluna da Anthropic vem de claude.com/pricing (consultado a October 3, 2026):

Within a session, switch models with /model claude-opus-5-5, or start immediately with claude --model claude-opus-5-5. The euro calculation, with examples of monthly usage and the point at which a subscription becomes more worthwhile, is available at Claude Code pricing in euros; calculate your own usage with the token cost calculator. All models and prices are listed on the pricing page.

Confirm with /status

Run claude. With ANTHROPIC_AUTH_TOKEN defined, the sign-in screen does not appear: the variable takes effect immediately. If the sign-in screen appears, Claude Code did not read any key. In that case, define it somewhere Claude Code reads before the first-launch assistant: an export in the shell or the env block in ~/.claude/settings.json. An env block in .claude/settings.json or .claude/settings.local.json for a project only applies, in an interactive session, after the first-launch assistant and the question about trusting the folder.

Dentro da sessão, escreva /status e procure duas linhas no separador Status (fonte: a official gateway documentation, consultada a October 3, 2026):

• Anthropic base URL should display https://api.kunavo.com. This line appears only when a gateway address is defined; if it is missing, ANTHROPIC_BASE_URL did not reach the session.
• The Auth token line should indicate ANTHROPIC_AUTH_TOKEN. If, instead, Login method appears with a claude.ai account, the variable was not read and the session is using the subscription.

Anyone who had already signed in with a subscription may see a warning at startup that two credentials are active (the message ends with auth may not work as expected). Requests go through the key; /logout clears the old sign-in.

To test the address and key before opening Claude Code, the documentation suggests making a request for a single output token, which uses an extremely small fraction of the balance. The commands read the shell variables, so define them there as well, even if they are already in settings.json.

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-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-5", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

A JSON response beginning with {"id":"msg_ means that the address and key work; in PowerShell, an id beginning with msg_ appears. A 401 means that the key was not recognized.

What changes with an API key

• Remote Control and voice dictation are unavailable. According to the gateway documentation, they are unavailable while ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or an apiKeyHelper is active; Remote Control is also disabled while ANTHROPIC_BASE_URL points to an address outside Anthropic.
• /fast displays fast mode as disabled. With only a bearer token, Claude Code treats fast mode as disabled.
• MCP tool search is disabled by default quando ANTHROPIC_BASE_URL aponta para um endereço fora da Anthropic (environment variable documentation, consultada a October 3, 2026).
• The /context numbers are estimates. O Kunavo não serve /v1/messages/count_tokens e, segundo a gateway compatibility documentation (consultada a October 3, 2026), sem esse endpoint o Claude Code recorre a uma estimativa baseada em caracteres.

Everything else—code, tools, subagents, MCP servers, hooks, and prompt caching—works as usual. More details are available in the Claude Code integration documentation (in English) and in Claude Code without a subscription (in English).

Paying the balance with MB WAY

Primeiro, a subscrição: uma subscrição Claude comprada no site paga-se só com cartão de crédito ou de débito (Anthropic help article about paid plans, consultado a October 3, 2026); numa subscrição feita na aplicação Claude para iOS ou Android, os meios de pagamento são os da App Store ou do Google Play. Os meios de pagamento do Kunavo, MB WAY incluído, não pagam o Claude Pro nem o Max: carregam o saldo da API do Kunavo, que é o que a Rota B usa.

O saldo carrega-se no checkout da Stripe. Os preços estão em dólares americanos; para quem compra em Portugal, a Stripe mostra o valor em euros. Segundo a Stripe documentation on Adaptive Pricing (consultada a October 3, 2026), essa conversão inclui uma comissão de 2–4% paga pelo comprador; quem escolhe pagar em dólares (com cartão, Apple Pay, Google Pay ou Link) não paga essa comissão, embora o banco possa aplicar a sua própria taxa de câmbio e comissões. O MB WAY só funciona em euros. No checkout em euros aparecem:

• MB WAY. Escolhe-se MB WAY, introduz-se o número de telemóvel e confirma-se a compra na aplicação MB WAY, através da notificação ou na área de atividade (Stripe on MB WAY e MB WAY on online purchases, consultados a October 3, 2026). Segundo a Stripe, são aceites números internacionais, mas a maioria dos clientes usa um número português, começado por +351.
• Cards (Visa, Mastercard), Apple Pay, Google Pay, and Link.

Não aparecem: referências Multibanco (pagamento por entidade e referência), PayPal, débito direto SEPA e Klarna, que só aparece a compradores nos Estados Unidos. A conversão para euros vem do Adaptive Pricing da Stripe, e a lista de meios de pagamento que ele disponibiliza inclui o MB WAY mas não o Multibanco. O MB WAY também permite gerar cartões virtuais MB NET para compras online (MB WAY on MB NET, consultado a October 3, 2026); não está confirmado que o campo do cartão do checkout os aceite, por isso o caminho seguro é escolher MB WAY diretamente.

What Stripe documents about MB WAY (checked on October 3, 2026):

• Per payment: between €0.50 and €5000.
• Per day: €1000 by default, adjustable up to €10,000 in the MB WAY app. Larger top-ups may exceed the default daily limit; in that case, increase it in the app before paying. Compare the euro amount shown at checkout with these limits.
• Recurring payments: not supported.
• The statement shows Stripe's name (Stripe Inc), along with the transaction amount.

1. Create a Kunavo account.
2. In Billing, choose an amount starting at US$ 10. Larger top-ups include extra balance: quem carrega US$ 100 recebe US$ 110; quem carrega US$ 1000 recebe US$ 1200; quem carrega US$ 5000 recebe US$ 6250.
3. At Stripe checkout, with the amount in euros, choose MB WAY, enter the mobile phone number, and confirm the purchase in the MB WAY app. The euro amount appears before confirmation.
4. At /app/keys, create the key and put it in ANTHROPIC_AUTH_TOKEN.

The balance is prepaid: there is no monthly fee, the balance does not expire, and failed requests are not charged. Automatic top-up works only with a saved card or Link; with MB WAY, you must always top up manually because, according to Stripe, MB WAY does not support recurring payments and is not saved for future payments. Kunavo does not issue invoices, with or without a tax identification number or VAT; top-up history is available in Billing. These payment methods top up only the Kunavo API balance. More on this topic at Paying for Claude with MB WAY.

Common errors

After installing

On the first launch in a project, enter /init: Claude Code scans the repository and writes a CLAUDE.md containing what it inferred: how to run the project, how to test changes, and which style rules it follows. Review this file and keep it short because it is loaded in every session. Between independent tasks, /clear starts a new conversation; during a long task, /compact summarizes the history so you can continue.

What you should know

• It is a pay-per-token API, not a Claude Pro or Max subscription. Those who use Claude Code for several hours every day usually pay less with a subscription; paying per token is worthwhile for irregular usage, and an inactive month costs nothing. The comparison in euros is available at Claude Code pricing in euros.
• Anyone working with an API key does not have Remote Control or voice dictation.
• Kunavo uses shared capacity, with no reserved quota or contractual guarantees; those who need them should contract directly with Anthropic.
• MB WAY is only for manual top-ups; automatic top-up requires a card or Link.
• The euro amounts shown at checkout already include Stripe's currency-conversion fee.

Frequently asked questions