shell-tools

Shell & Tools

Environment facts about the shell, the file tools, and the CLIs around them. These do not become knowable through reasoning -- they are properties of zsh, jq, Python, and the tool layer.

Sequencing Fallible Calls

Wrong -- independent Bash calls issued in parallel; one failure kills all siblings:

# Parallel call 1: pnpm run typecheck
# Parallel call 2: pnpm run lint
# Parallel call 3: pnpm run test

Right -- chain sequentially so each result survives:

pnpm run typecheck 2>&1 ; pnpm run lint 2>&1 ; pnpm run test 2>&1

Use && when a later step is meaningless after an earlier failure, ; when you want every result regardless.

Quoting and Escaping

Inside single quotes, every character is literal. Escaping an operator there inserts a real backslash into the string and breaks the consumer.

Wrong -- backslash reaches jq and Python as data:

jq '.[] | select(.name \!= "review")'   # jq: INVALID_CHARACTER
python3 -c 'assert x \!= y'             # SyntaxError

Right -- write the operator plainly inside '...':

jq '.[] | select(.name != "review")'
python3 -c 'assert x != y'

Complex Regex in zsh

Wrong -- zsh treats !, {, and } specially before the command ever runs:

grep -oP '(?<=version":")[^"]+' package.json
# zsh: event not found

Right -- use the built-in Grep tool, a dedicated linter, or wrap in bash:

bash -c 'grep -oP '"'"'(?<=version":")[^"]+'"'"' package.json'

Reach for the built-in Grep tool first. It takes the pattern as data, so no shell parsing happens at all.

Paths

The file tools do not expand ~, and the shell's working directory resets between Bash calls.

Wrong -- tilde in a file tool, relative path across calls:

Read("~/code/project/src/index.ts")     # no such file

cd ../other-project && pnpm test        # cwd already reset; ../ is wrong

Right -- absolute paths everywhere, and cd inside the same call:

Read("/Users/you/code/project/src/index.ts")