Command line (wirelens)

WireLens for Mac comes with a command line tool, wirelens. It reads the capture while the app is recording, writes rules, and asks the running app to start or stop capture, change the system proxy or install the certificate.

The tool is free. Rules you add from it count against the same free allowances as the app. A few commands reach features that need WireLens Pro: export csv, protobuf --path, proxy upstream set, cert identity add, network-extension install and enable, mcp inspect, and config set for a Pro setting such as HTTP/3 decryption. On the free plan these exit with code 6, as does a rule past its allowance.

Install#

There is nothing extra to download. The tool ships inside the app, at /Applications/WireLens.app/Contents/Helpers/wirelens, and always matches the version of WireLens that recorded your capture.

Installing the app does not add wirelens to your PATH. Until you link it, run it by its full path:

/Applications/WireLens.app/Contents/Helpers/wirelens ls --status 5xx

To type wirelens instead, link it once. In the app, choose Help ▸ Install Command Line Tool…, or run:

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

Both do the same thing: /usr/local/bin/wirelens becomes a link to the copy inside the app and stays on the app's version through every update. If that folder needs an administrator, both hand you the matching sudo ln -sf line to copy. Open WireLens once before you link it: until the app has created its data folder, install-symlink stops with exit code 3.

The rest of this page writes wirelens on its own, which assumes you have linked it. If you have not, put the full path in front of any command.

The live session#

Run wirelens with no arguments in a terminal for an interactive session (wirelens watch, repl and top open the same thing). Traffic streams above a prompt pinned to the bottom of the window. Off a terminal, for example in a script, plain wirelens prints the help instead.

Text that does not start with / searches inside 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
wirelens llm spend --session 5e8f

• ls (or list) filters with --host, --method, --status, --path, --search, --content-type, --failed, --min-duration (ms), --since, --session, --after and --limit (default 50). grep and hosts take the same filters.
• --status takes a code (404) or a class (5 or 5xx). --since takes 90s, 10m, 2h, 1d, an ISO 8601 date or epoch seconds. Any other value stops with exit code 2.
• llm spend totals what AI-model calls cost, per model, and takes the same filters (Pro). show on a model call prints its tokens, and with Pro its cost.
• show prints one flow. --body request or --body response prints a body, --json-path narrows JSON, --raw prints the bytes as captured, and --limit caps how many bytes print.
• 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 har --after <id> --out new.har
wirelens export csv --out capture.csv --columns method,status,url --bom
wirelens export curl <id>
wirelens export raw <id> --out request.txt
wirelens export session --out ./checkout-bug

• har and csv take the same filters as ls. --after <id> exports only flows newer than that one, for incremental exports.
• csv also takes --columns, --bom (for Excel) and --no-header.
• raw writes one flow as a raw HTTP request message.
• session writes a session package folder with bodies and WebSocket frames, which WireLens reopens as the capture it was. --session <id> picks a run.

Rules#

wirelens rules list
wirelens rules get <id>
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 update <id> --set enabled=false
wirelens rules rm <id>

rewrite takes --method, --host, --path, --set-header, --remove-header, --set-query, --remove-query, --request-body, --status, --set-response-header, --remove-response-header, --response-body and --note. wirelens help shows a short form; run wirelens rules rewrite without --pattern to print the full list.

By id, enable, disable, rm and get work on any rule. update <id> --set field=value changes one field in place and keeps the rule's id and position; the field names are the ones rules get prints. rules create reads one rule as a JSON object on stdin, with a kind field (map-local, map-remote, rewrite, breakpoint, script, reverse-proxy, dns, allow, block, ssl, protobuf):

echo '{"kind":"map-local","pattern":"https://api.example.com/v2/cart","status":200,"body":"{}"}' | wirelens rules create

Rules take effect on the next request, with no restart. A rule with no pattern is refused. rules writes straight away and ignores --dry-run.

Settings#

wirelens config get
wirelens config set <name> true
wirelens settings export --out settings.json
wirelens settings export --tools map-local,rewrite --enabled-only
wirelens settings import settings.json --dry-run
wirelens settings tools

• config get [NAME] reads settings and config set NAME true|false flips a switch. config set writes straight away and ignores --dry-run.
• settings export writes a whole rule set to share. Secrets inside rules are left out unless you pass --include-secrets. --tools picks tools by id (settings tools lists them) and --enabled-only keeps only rules that are switched on.
• settings import adds the rules in a file. --update changes rules that already exist, --replace replaces your rules with the file's, --merge merges them, and --dry-run reports what would change.

From Proxyman or Charles#

wirelens import session.proxymansessionv2
wirelens import rules.config --dry-run
wirelens import --proxyman-rules
wirelens import --charles-settings
wirelens convert capture.chlsj --out capture.har

import opens a session (.proxymansessionv2, .proxymanlogv2, .chlsj, .chlz, .chls, .har, .wirelens) in the running app as its own run, and imports a rule set (a Proxyman .config export or Charles settings) straight away. --proxyman-rules and --charles-settings read the copy installed on this Mac. convert writes a HAR from a Proxyman or Charles session and does not need the app. settings import accepts the same rule files.

Control the app#

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

Most of these ask the running app to act, because the app owns the listener and the helper. With WireLens closed they exit with code 4 and say so. Three work with the app closed: capture status reads what the app last wrote, and proxy upstream and cert identity write the configuration directly.

Add --dry-run to any of these, or to import and mcp policy, to see what a command would do without doing it.

MCP setup#

The same tool sets up the MCP server for your AI agents:

Client names: claude-code, claude-desktop, codex, gemini, cursor. claude on its own means Claude Desktop.

Global options#

--json (output for scripts), --no-color, --store DIR (read a capture other than the default), --dry-run, --timeout SECONDS (how long to wait for the app), --version and --help.

Exit codes#

Safe while the app records#

Reading a live capture from the command line leaves it untouched. If the capture was written by another version of WireLens, the tool stops with code 7. wirelens doctor checks the capture and the configuration when something looks off.

To rename or delete sessions, annotate flows, test scripts, diagnose setup, set up simulators or inject into Electron apps, use the MCP server.