Claude Code CLI

# Install globally
$ npm install -g @anthropic-ai/claude-code

# Navigate to your project
$ cd ~/playwright-project

# Start Claude Code — browser opens for auth on first run
$ claude

# Or: use API key instead of subscription
$ export ANTHROPIC_API_KEY="sk-ant-..."
$ claude

# See which version you're on
$ claude --version

# Update now — don't wait for the background check (native + npm installs)
$ claude update

# npm global install: upgrade explicitly.
# Avoid `npm update -g` — it respects the old semver range and may not bump.
$ npm install -g @anthropic-ai/claude-code@latest

# Homebrew / WinGet don't auto-update — upgrade manually.
# On these installs `claude update` silently does nothing; use the package manager.
$ brew upgrade --cask claude-code   # Claude Code is a cask — the --cask flag is required
> winget upgrade Anthropic.ClaudeCode

# Diagnose the install + see the result of the last auto-update attempt
$ claude doctor

# Aliases resolve to the current recommended model for your account —
# they update automatically as new models ship.
$ claude --model sonnet    # Sonnet 5 on the API/Pro; Sonnet 4.6 on Bedrock/Vertex/Foundry
$ claude --model opus      # Opus 4.8 on the API; Opus 4.7 on Claude Platform on AWS
$ claude --model haiku     # Haiku 4.5 everywhere
$ claude --model fable     # Fable 5 — hardest, longest-running tasks (not default anywhere)

# Pin an exact version instead of an alias (recommended for CI/CD):
$ claude --model claude-sonnet-5
$ claude --model claude-opus-4-8

# opusplan: Opus for planning, Sonnet for execution — best of both
$ claude --model opusplan

# Check what's active right now
$ claude
> /status

# Force the 1M window on an alias or full model name
/model sonnet[1m]
/model opus[1m]
/model claude-opus-4-8[1m]

# See what's consuming the context window right now
/context

# Change the auto-compact threshold for Sonnet 5's 1M window (default ~967K)
$ export CLAUDE_CODE_AUTO_COMPACT_WINDOW=800000

# Cap Sonnet 5 at a 200K window on purpose (e.g. to bound cost)
$ export CLAUDE_CODE_DISABLE_1M_CONTEXT=1

# Interactive session
$ claude

# One-shot: single prompt, get answer, exit
$ claude -p "explain the page object pattern in tests/pages/"

# Continue last conversation
$ claude --continue    # or -c

# Pick from recent sessions
$ claude --resume      # or -r

# Pipe input
$ cat test-results/errors.log | claude -p "explain these test failures"

# JSON output for scripting
$ claude -p "list all spec files" --output-format json

# Specify model — alias or full ID (see Pricing & Models → Selecting a Model)
$ claude --model sonnet    # Sonnet 5 — daily coding, default on Pro
$ claude --model opus      # Opus 4.8 — flagship for complex tasks
$ claude --model fable     # Fable 5 — hardest, longest-running tasks

# Best practice: append rules for Playwright project
$ claude --append-system-prompt "Always use Page Object Model. Import test from src/fixtures/base.fixture.ts, not @playwright/test."

# CI/CD: run with rules from file
$ claude -p "review tests/" --append-system-prompt-file .claude/ci-rules.md

# Allow specific tools
$ claude --allowedTools "Read,Grep,Glob,Write,Edit"

# YOLO mode — skip all prompts (containers only!)
$ claude --dangerously-skip-permissions

~/.claude/
    CLAUDE.md              ← Global: personal defaults for ALL projects
    settings.json          ← Global permissions, model preferences
    keybindings.json       ← Your keyboard shortcuts

./ (project root)
    CLAUDE.md              ← Project: team-shared (commit to git!)
    CLAUDE.local.md        ← Project: personal overrides (gitignored)
    .claudeignore          ← Files Claude should never read

./.claude/
    settings.json          ← Project settings (hooks, permissions)
    skills/
        SKILL.md           ← Project-wide skill
        playwright/
            SKILL.md       ← Domain-specific skill

./tests/
    CLAUDE.md              ← Directory-level: rules only for tests/

# Playwright E2E Test Framework

## Stack
Playwright 1.50+ · TypeScript 5.6+ · Faker.js · dotenv

## Commands
npm test              # run all tests
npm run test:ui       # Playwright UI mode
npm run test:chrome   # chromium only
npm run lint          # ESLint check
npm run typecheck     # TypeScript strict check

## Architecture
src/pages/       — Page Objects (extend BasePage)
src/fixtures/    — Custom Playwright fixtures (DI)
src/api/         — API client classes
src/utils/       — Env config, helpers, test data generator
src/data/        — Static test data, routes, users
tests/           — Test specs by feature

## Critical Rules
- ALWAYS import { test, expect } from `src/fixtures/base.fixture.ts`
  NOT from `@playwright/test`
- Use `data-testid` for selectors, never CSS classes
- Page objects: locators as readonly props, actions as methods
- Env vars via `src/utils/env.config.ts` — never hardcode
- Auth handled by `tests/auth.setup.ts` — tests start authenticated

## Naming
Files: kebab-case · Classes: PascalCase · Test IDs: kebab-case
Tests: start with "should" — "should login with valid credentials"

## Gotchas
- page.waitForTimeout() is an anti-pattern — use expect/waitForURL
- API tests don't use storageState — they get own token in beforeAll
- Never commit page.pause() — debug only

.claude/skills/
    SKILL.md                     ← Main project skill (auto-loaded)
    playwright-tests/
        SKILL.md                 ← Activated: "write a test", "fix spec"
    api-testing/
        SKILL.md                 ← Activated: "API test", "endpoint test"
    code-review/
        SKILL.md                 ← Activated: "review this", "check quality"

---
name: playwright-tests
description: >
  Activated when writing, fixing, or modifying Playwright tests.
  Triggers: test, spec, e2e, playwright, page object, fixture.
---

# Playwright Test Guidelines

## Creating a New Test
1. Does it need auth? Import from the correct fixture:
   - Auth tests → `src/fixtures/auth.fixture.ts`
   - Regular tests → `src/fixtures/base.fixture.ts`
   - API only → `@playwright/test` directly

2. Create page object first if it doesn't exist:
   - Extend `BasePage` from `src/pages/base.page.ts`
   - Locators = readonly properties via `this.byTestId()`
   - Actions = methods, Assertions = `expectX()` methods

3. Register page object in `src/fixtures/base.fixture.ts`

## Locator Priority
1. getByTestId() ← most reliable
2. getByRole()   ← semantic
3. getByText()   ← visible text
4. getByLabel()  ← form fields
5. locator()     ← last resort

## Anti-Patterns
✗ page.waitForTimeout(ms) — use auto-waiting
✗ Hardcoded URLs — use ROUTES from data/routes
✗ Hardcoded creds — use USERS from data/users
✗ page.pause() in committed code

{
  "hooks": {
    "post-edit": [
      {
        "command": "npx eslint --fix $FILE 2>/dev/null || true",
        "description": "Auto-fix lint after every edit"
      }
    ],
    "pre-commit": [
      {
        "command": "npm run typecheck && npx playwright test --reporter=list 2>&1 | tail -20",
        "description": "Type-check + quick test before commit"
      }
    ]
  }
}

# 1. Ask for one directly — include the keyword "ultracode" (or say
#    "use a workflow" in your own words)
> ultracode: migrate 240 spec files from Playwright 1.40 to 1.50 API,
  one subagent per directory under tests/. Each subagent should
  update imports, replace page.waitForTimeout() with explicit waits,
  run the suite for that dir, and report files touched + blockers.

# 2. Let Claude decide for every substantive task this session
/effort ultracode

# Monitor any run: phases, agent count, tokens, elapsed time
/workflows

# Built-in workflow for cross-checked research
/deep-research "What changed in Playwright's clock API between 1.40 and 1.50?"

# Don't wait for auto-compact at 95%. Do it manually at ~70%:
/compact focus on the auth setup refactoring decisions

# You can specify what to keep:
/compact keep only the page object patterns and fixture changes

# Prevent Claude from reading these — saves thousands of tokens
node_modules/
dist/
build/
playwright-report/
test-results/
blob-report/
coverage/
*.lock
*.min.js
*.min.css
*.map
*.log

# Switch in-session (aliases resolve to the current recommended model):
/model haiku      # for exploration
/model sonnet     # back to normal work
/model opus       # for the hard part
/model fable      # for the hardest, longest-running part

# Reasoning depth is a separate, complementary lever:
/effort low       # short/scoped tasks, latency-sensitive
/effort high      # default on Fable 5, Sonnet 5, Opus 4.8 — balanced
/effort ultracode # plans a dynamic workflow for every substantive task

# Subagent gets its own clean context — doesn't pollute yours
> Use a subagent to explore the src/api/ directory
  and report: what endpoints exist, error handling patterns,
  and whether we have retry logic.

# Claude spawns a focused agent, explores, reports back
# Your main context stays clean

/rename playwright-auth-refactor
/rename adding-checkout-page-object

# Later, resume by name — no need to re-explain context:
$ claude --resume

# Picks up exactly where you left off — zero re-explanation needed
$ claude --continue    # or: claude -c

# In-session breakdown (skills, subagents, MCP servers, session cost):
/usage

# Authoritative billing (API workspaces):
https://platform.claude.com/usage

# Rule: compact at 70%, /clear at task boundaries

playwright-project/
    CLAUDE.md                    ← Project brain (section above)
    CLAUDE.local.md              ← Your personal overrides (.gitignored)
    .claudeignore                ← Exclusions (section above)
    .claude/
        settings.json            ← Hooks + permissions (hooks section)
        skills/
            playwright-tests/
                SKILL.md         ← Test writing skill (skills section)
    .eslintrc.json               ← Linting rules Claude follows
    tsconfig.json                ← TypeScript strict mode config
    prettier.config.js           ← Formatting rules
    .editorconfig                ← Editor settings
    .env.example                 ← Template for environment vars
    .gitignore                   ← Include .env, auth/, reports/
    playwright.config.ts         ← Multi-project Playwright config

{
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep", "Write", "Edit",
      "Bash(npm run *)",
      "Bash(npx *)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  },
  "hooks": {
    "post-edit": [{
      "command": "npx eslint --fix $FILE 2>/dev/null || true",
      "description": "Auto-lint after every edit"
    }],
    "pre-commit": [{
      "command": "npm run typecheck && npm run lint",
      "description": "Quality gate before commit"
    }]
  }
}

# 1. Which binary runs — and are there several on your PATH?
$ which -a claude

# 2. Follow it to the real install (reveals Homebrew cask / npm / native)
$ readlink -f "$(which claude)"

# 3. Your running build vs. the latest published on npm
$ claude --version
$ npm view @anthropic-ai/claude-code version

# 4. One-shot health check: install method, auth, last auto-update attempt
$ claude doctor

# A global install lives inside ONE Node version:
#   ~/.nvm/versions/node/v24.12.0/bin/claude
# After `nvm use 20` that bin dir leaves PATH and claude "disappears".

# Fix A — pin a default Node so the same install stays on PATH
$ nvm alias default 24

# Fix B — (re)install under whichever Node you actually run
$ nvm use 24 && npm install -g @anthropic-ai/claude-code@latest

# Is a key set that you didn't mean to use?
$ echo $ANTHROPIC_API_KEY

# Use your subscription instead — unset, then relaunch
$ unset ANTHROPIC_API_KEY

# Inside a session: confirm active auth + model
> /status

# Switch or refresh the browser login
> /login