Set up the command-line client

Use joesproxyctl to ask the same question across two test runs. Start with the executable bundled with the app you’re testing. If JoesProxy is installed in Applications, check it from Terminal:

"/Applications/JoesProxy.app/Contents/MacOS/joesproxyctl" version

If the app is elsewhere, substitute its actual location. The examples below use the short name; use the quoted executable path instead if your shell reports “command not found.” That error occurs before any attempt to reach JoesProxy.

Learn the command surface offline

1. Look up docs search and use its example with a topic such as recording fidelity.
2. Copy a returned topic identifier into docs read. Read the matching topic rather than treating a search snippet as a complete set of instructions.
3. Expected result: documentation content from the CLI’s own help bundle. This does not require captured traffic and does not demonstrate authentication to the live Mac app.

For example, the following read-only pair searches for recording fidelity, then reads the matched topic and section:

joesproxyctl docs search --query "recording fidelity" --format json
joesproxyctl docs read --topic hub-recordingSaveModes --section p1 --format markdown

The search result includes the topic ID hub-recordingSaveModes and matched section p1. The second command explains that Recording Fidelity controls saved bodies, separately from live Long Capture Storage. If your search returns another match, use the topic and section it actually returned. This exercise does not start the proxy.

First investigation: get the setup checklist without connecting

Run joesproxyctl setup guide --format markdown for the human-readable setup guide. Choose --format json when you want structured guidance for a script. Then run joesproxyctl doctor --json. Without an enrolled credential, doctor reports local bootstrap information only. That is a useful offline result, not a live health check. Neither command changes your phone’s settings or establishes that traffic was captured.

Check live connectivity separately

1. Start MCP on the Mac and use the endpoint displayed there. Run joesproxyctl doctor in a real terminal.
2. If credentials are missing, use joesproxyctl auth login interactively and review the requested client enrollment on the Mac. Do not paste credentials into a script or a report.
3. Check the resulting status with joesproxyctl auth status. Before asking for session data, use the target setup guide and confirm that the target generated one synthetic request. Use the CLI reference for the exact command and output mode.

Match a terminal result to an app action

With an enrolled client and a routed test app, refresh one known screen. Run joesproxyctl sessions list --limit 5 and compare the returned sessions with Table on the Mac. Look for the host and time of the refresh, not simply the last row. If unrelated traffic fills the list, use sessions search to narrow it. A successful but empty list is different from an authentication error: establish that the app made a new captured request before changing permissions.

Finish and troubleshoot

Inspect joesproxyctl cleanup status before ending a live experiment. A status query reports state; it does not disable a rule. Stop test effects deliberately, verify normal routing, and log out or remove temporary grants when appropriate.

FAQ: offline help works but a live query fails. The executable can read its own help even when the MCP server is stopped or the client has no grant. Check the listener named in the error, authentication, and requested capability before changing device routing. See permission troubleshooting.