PART 2 SYLAS LYU · FM-01 · REV B

FOUNDATIONS

Terminal and JSON basics, which everything technical depends on.

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

How a command is built

POWERSHELL · C-01
winget install --id Git.Git -e

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?

POWERSHELL · C-02
Get-Location
Get-ChildItem

Expected: 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

POWERSHELL · C-03
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.txt

Expected: 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

Installing the tools this guide uses

winget is Windows' built-in package manager. Run winget --version first; any version number means it works.

POWERSHELL · C-04
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:

POWERSHELL · C-05
git --version
node --version
npx --version
uv --version
jq --version

Expected: 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:

POWERSHELL · C-06
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Exit 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.

POWERSHELL · C-07
git --version
$LASTEXITCODE
git notarealcommand
$LASTEXITCODE

Expected: 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.

POWERSHELL · C-08
Get-ChildItem ~ | Sort-Object LastWriteTime -Descending | Select-Object -First 5
Get-ChildItem ~ > listing.txt

Expected: 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.

POWERSHELL · C-09
$env:PATH -split ';'
$env:GREETING = "hello"
$env:GREETING

Expected: one folder per line, then hello. A variable set this way lasts until you close the window. To keep one permanently:

POWERSHELL · C-10
[Environment]::SetEnvironmentVariable('GREETING', 'hello', 'User')

EX-03 Run Python without installing it by hand

POWERSHELL · C-11
cd ~\claude-practice
uv python install
Set-Content hello.py 'print("Hello from Python")'
uv run hello.py

Expected: uv downloads a Python version if needed, then prints Hello from Python.

Git Bash and WSL

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:

POWERSHELL · C-12
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:

POWERSHELL · C-13
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.txt

Expected: 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.

  1. An object sits in curly braces and holds "key": value pairs separated by commas.
  2. A list (array) sits in square brackets: ["red", "blue"].
  3. Keys and text values use double quotes. Single quotes are invalid.
  4. A value is text, a number, true, false, null, an object or a list.
  5. 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.
  6. 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:

JSON · C-14
{
  "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

POWERSHELL · C-15
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.json

Expected, 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

POWERSHELL · C-16
Set-Content bad1.json '{"name": "test",}'
Set-Content bad2.json '{name: "test"}'
jq . bad1.json
jq . bad2.json

Expected: 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:

POWERSHELL · C-17
'{"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):

JSON · C-18
{"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:

YAML · C-19
---
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.