Command line (wirelens)

WireLens for Mac ships a command line tool, wirelens, inside the app. It reads the capture safely while the app is recording, writes rules, and asks the running app to start or stop capture.

Install#

The tool lives at /Applications/WireLens.app/Contents/Helpers/wirelens. Put it on your PATH with:

/Applications/WireLens.app/Contents/Helpers/wirelens install-symlink

That creates /usr/local/bin/wirelens as a link to the copy inside the app, so the tool always matches the app's version when WireLens updates.

The live session#

Run wirelens with no arguments in a terminal for an interactive session. Live traffic streams above a prompt pinned to the bottom of the window, and you work with slash commands:

Anything that is not a command is a search across bodies.

Read the capture#

wirelens ls --host api.example.com --status 5xx
wirelens ls --method POST --min-duration 1000 --since 10m --json
wirelens show 3f9c --body response --json-path '$.error'
wirelens grep 'invalid_grant'
wirelens hosts
wirelens sessions

• ls filters with --host, --method, --status (exact, or a class like 5xx), --path, --search, --content-type, --failed, --min-duration, --since, --session and --limit.
• show prints one flow; --body request or --body response prints a body, --json-path narrows JSON, --raw prints bytes as captured.
• Flow ids can be shortened to any unique prefix.
• Every read command takes --json for scripts.

Export#

wirelens export har --out capture.har
wirelens export har --session <id> --out run.har
wirelens export csv --out capture.csv
wirelens export curl <id>

Rules#

wirelens rules list
wirelens rules ssl add api.example.com
wirelens rules block add ads.example.com
wirelens rules map-local --pattern 'https://api.example.com/v2/catalog*' --content '{"items":[]}'
wirelens rules map-remote --from 'https://api.example.com/*' --to 'https://staging.example.com'
wirelens rules rewrite --pattern 'https://api.example.com/*' --set-header 'X-Debug: 1'
wirelens rules breakpoint --host api.example.com --path /v2/cart
wirelens rules disable <id>
wirelens rules rm <id>

There are verbs for every rule type: ssl, bypass (the SSL Exclude list), insecure, block, allow, throttle, map-local, map-remote, rewrite, breakpoint, script, reverse-proxy, dns and protobuf, plus enable, disable and rm by id. A blank pattern is refused, and the free plan's limits apply here exactly as they do in the app.

Control the app#

wirelens capture start
wirelens capture status
wirelens proxy restore
wirelens cert install --scope user
wirelens open <id>
wirelens clear

capture, proxy, cert, clear and open ask the running app to act, since the proxy and its helper belong to the app. With WireLens closed they exit with code 4 and say so. Add --dry-run to see what a command would do without doing it.

Settings#

wirelens settings export --out settings.json
wirelens settings import settings.json --dry-run
wirelens config get
wirelens config set <key> true

Settings exports leave secrets inside rules out unless you pass --include-secrets.

Exit codes#

Safe while the app records#

The command line never changes the capture itself while you read it. It opens the store in a read-only mode that cannot trigger an index rebuild, and it refuses a capture written by a newer or older version of WireLens (exit 7) instead of migrating it and risking what the app is recording. wirelens doctor checks the store and the app's state when something looks off.