FOUNDATIONS
Terminal and JSON basics, which everything technical depends on.
- PARTP2
- SECTIONS2
- PLATFORMWINDOWS 11
- REVISIONB · 7 OCT 2026
SECTION 04
Terminal and CLI basics on Windows
A CLI (command line interface) is a program you control by typing commands instead of clicking. On Windows you type them into PowerShell, and about fifteen commands cover nearly everything in this guide.
Opening PowerShell
- Press Win + X, then choose Terminal or Windows PowerShell.
- PowerShell's prompt looks like
PS C:\Users\<you>>. The older CMD prompt has noPS. The two use different commands, so check before pasting anything. - Pick the entry without "(x86)" in its name; Anthropic's terminal guide notes the x86 one is 32-bit and Claude Code rejects it.
- Paste with Ctrl + V or a right-click. Press Ctrl + C to stop a running command. Up arrow recalls earlier commands. Tab completes file and folder names.
How a command is built
winget install --id Git.Git -ewingetis the program.installis a subcommand: which job the program should do.--id Git.Gitis a flag with a value. Flags start with-or--.-eis a flag with no value; for winget it means "exact match".
Nearly every CLI follows this shape, including claude, git, uv and npx. To see a program's options, add --help: winget --help, git --help, claude --help. For PowerShell's own commands, use Get-Help <command>.
EX-01 Where am I, and what is here?
Get-Location
Get-ChildItemExpected: the first prints your current folder, usually C:\Users\<you>. The second lists the files and folders in it. pwd, ls and dir are short aliases for the same two commands.
EX-02 Make a practice folder and a file
cd ~
mkdir claude-practice
cd claude-practice
Set-Content -Path hello.txt -Value "first line"
Add-Content -Path hello.txt -Value "second line"
Get-Content hello.txtExpected: first line and second line printed on two lines. You will reuse this folder for later exercises.
Everyday commands
| Task | PowerShell command | Short alias |
|---|---|---|
| Show current folder | Get-Location |
pwd |
| List contents | Get-ChildItem |
ls, dir |
| Change folder | Set-Location <path> |
cd <path> |
| Go up one level | cd .. |
|
| Go home | cd ~ |
|
| Make a folder | New-Item -ItemType Directory <name> |
mkdir <name> |
| Show a file | Get-Content <file> |
cat <file> |
| Write a file | Set-Content <file> "<text>" |
|
| Copy | Copy-Item <from> <to> |
cp |
| Move or rename | Move-Item <from> <to> |
mv |
| Delete (no Recycle Bin) | Remove-Item <path> |
rm |
| Find where a program lives | Get-Command <name> |
gcm |
| Clear the screen | Clear-Host |
cls |
Remove-Item skips the Recycle Bin. Check the path before pressing Enter.
Paths
- Absolute path: the full address, such as
C:\Users\<you>\claude-practice\hello.txt. - Relative path: from where you are now.
.\hello.txtis "hello.txt in this folder";..\is the folder above. - Home:
~,$HOMEor$env:USERPROFILEin PowerShell. Some programs started from PowerShell, such ascode, do not understand~, so this guide writes$HOMEin those commands.%USERPROFILE%means the same folder in File Explorer's address bar and in CMD, but not in PowerShell. - Paths with spaces need quotes:
cd "C:\Users\<you>\OneDrive\My Notes".
Installing the tools this guide uses
winget is Windows' built-in package manager. Run winget --version first; any version number means it works.
winget install --id Git.Git -e --source winget
winget install --id OpenJS.NodeJS.LTS -e
winget install --id=astral-sh.uv -e
winget install jqlang.jq
winget install --id Microsoft.VisualStudioCode -e| Tool | Why you want it |
|---|---|
| Git for Windows | Version history for code; also provides Git Bash, which Claude Code uses for its Bash tool (optional per Anthropic's docs; without it Claude Code uses PowerShell) |
| Node.js LTS | Provides npx, which runs many MCP servers and the MCP Inspector |
| uv | Installs Python and runs Python scripts and Python MCP servers |
| jq | Reads and filters JSON on the command line; used in hook scripts |
| VS Code | Code editor; optional, but the easiest way to edit config files |
Close PowerShell, open a new window, then confirm each one:
git --version
node --version
npx --version
uv --version
jq --versionExpected: a version number from each. The Git and jq IDs above come from git-scm.com's and jqlang.org's install pages, uv's from Astral's docs. Tested: winget show found every ID above, plus Microsoft.PowerShell (PowerShell 7) and Anthropic.ClaudeCode, with winget 1.29. If an ID ever stops working, winget search <name> lists the current one.
If npx fails with "running scripts is disabled on this system", PowerShell's script policy is blocking npm's launcher. Microsoft's documentation gives Restricted as the default policy on Windows client computers, which blocks all scripts. Check the policy in force with Get-ExecutionPolicy (tested: the PC this guide was checked on returned RemoteSigned, set for LocalMachine, so nothing needed changing). If it says Restricted or AllSigned, run this once:
Set-ExecutionPolicy -Scope CurrentUser RemoteSignedExit codes
Every program reports a number when it finishes. 0 means success; anything else means failure. Hooks in section 13 rely on this, since exit code 2 tells Claude Code to block an action.
git --version
$LASTEXITCODE
git notarealcommand
$LASTEXITCODEExpected: 0 after the first command and 1 after the second (git also prints an error). This uses Git, installed in the previous step.
Pipes and redirection
A pipe | passes one command's output into the next. > writes output to a file; >> appends.
Get-ChildItem ~ | Sort-Object LastWriteTime -Descending | Select-Object -First 5
Get-ChildItem ~ > listing.txtExpected: the five most recently changed items in your home folder, then a new listing.txt holding the full list.
Environment variables and PATH
Environment variables are named settings that programs read. PATH is the list of folders Windows searches when you type a program's name. The error "is not recognized as the name of a cmdlet" almost always means the program's folder is not on PATH, or the window was opened before the install finished.
$env:PATH -split ';'
$env:GREETING = "hello"
$env:GREETINGExpected: one folder per line, then hello. A variable set this way lasts until you close the window. To keep one permanently:
[Environment]::SetEnvironmentVariable('GREETING', 'hello', 'User')EX-03 Run Python without installing it by hand
cd ~\claude-practice
uv python install
Set-Content hello.py 'print("Hello from Python")'
uv run hello.pyExpected: uv downloads a Python version if needed, then prints Hello from Python.
Git Bash and WSL
- Git Bash comes with Git for Windows and understands Linux-style commands (
ls -la,cat,grep). Claude Code uses it behind the scenes when present. - WSL (Windows Subsystem for Linux) runs a full Linux system inside Windows. Anthropic lists it as the route for sandboxed command execution. Not needed for anything in this guide.
Git in a few commands
Git keeps a history of a folder, so any saved state can be brought back. Recipe 6, /rewind and the safety table in section 17 lean on it. Once per computer, tell Git who you are:
git config --global user.name "Your Name"
git config --global user.email "you@example.com"| Command | What it does |
|---|---|
git init |
Start tracking the current folder (once per project) |
git status |
Show what changed since the last snapshot |
git add . |
Stage every change for the next snapshot |
git commit -m "<message>" |
Save a snapshot (a commit) with a description |
git log --oneline |
List snapshots, newest first |
git diff |
Show unsaved changes line by line |
git restore <file> |
Throw away unsaved changes to one file |
Try it in a throwaway folder:
mkdir ~\claude-practice\git-test
cd ~\claude-practice\git-test
Set-Content notes.txt "version one"
git init
git add .
git commit -m "First snapshot"
Set-Content notes.txt "version two"
git diff
git restore notes.txt
Get-Content notes.txtExpected: an "Initialized empty Git repository" line, a one-file commit summary, a diff showing -version one and +version two, and finally version one, because git restore brought back the committed text.
SECTION 05
JSON basics
JSON is the text format behind almost every config file in this guide: settings.json, .mcp.json, plugin.json, the data a hook receives, and the messages MCP servers exchange. Six rules cover it.
- An object sits in curly braces and holds
"key": valuepairs separated by commas. - A list (array) sits in square brackets:
["red", "blue"]. - Keys and text values use double quotes. Single quotes are invalid.
- A value is text, a number,
true,false,null, an object or a list. - No comma after the last item, and no comments. Claude Code's hooks troubleshooting page lists both as reasons a settings file silently fails to load.
- Backslashes in Windows paths are doubled:
"C:\\Program Files\\Git\\bin\\bash.exe".
A real example, the shape Anthropic's setup page uses to point Claude Code at Git Bash:
{
"env": {
"CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe",
"GREETING": "hello"
}
}The outer object has one key, env, whose value is another object holding two "key": "text" pairs separated by a comma. The GREETING line is only there to show the comma rule; leave it out of a real settings file.
EX-04 Read JSON with jq
cd ~\claude-practice
Set-Content good.json '{"name": "test", "colours": ["red", "blue"], "active": true}'
jq . good.json
jq '.name' good.json
jq -r '.colours[]' good.json
jq '.colours | length' good.jsonExpected, in order: the object printed with indentation; "test"; red and blue on separate lines (-r removes the quotes); 2.
The outer single quotes matter in PowerShell. They pass the text through unchanged, double quotes included.
EX-05 Break it on purpose
Set-Content bad1.json '{"name": "test",}'
Set-Content bad2.json '{name: "test"}'
jq . bad1.json
jq . bad2.jsonExpected: both print a jq: error parse message. The first has a trailing comma; the second has an unquoted key. When a config file "does nothing", running jq . <file> is the fastest check.
EX-06 Parse the kind of JSON a hook receives
Claude Code sends hooks a JSON object on standard input. This sample has the same shape as the one in Anthropic's hooks guide:
'{"tool_name":"Bash","tool_input":{"command":"npm test"}}' | jq -r '.tool_input.command'Expected: npm test. Section 13 uses exactly this pattern.
JSON messages as a control channel
The "JSON control channel" in that product claim is a general pattern: a program accepts commands written as JSON objects and answers in JSON. MCP works this way. It uses JSON-RPC 2.0 messages, so a client asking a server to list its tools sends an object shaped like this (illustrative):
{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}You never type these by hand in normal use. The MCP Inspector in section 11 shows them going back and forth, and the end of section 15 gives a routine for getting to know any app that offers a CLI, a JSON channel or an MCP server.
YAML, briefly
Skill and subagent files start with YAML frontmatter instead of JSON. YAML uses key: value lines, no braces, and indentation for nesting:
---
name: report-helper
description: Answers questions about a report from its sections
---The --- lines mark where the frontmatter starts and ends. Claude Code's skills page notes that the opening --- has to be the file's first line.