Report Bug

The hardest part of a bug report is the evidence. Report Bug turns the requests behind a bug into everything a developer needs:

• a summary that lists the failing requests first, each with its response, trace and a cURL command to reproduce it;
• a redacted HAR and Cloak Proxy session;
• a flow that replays the requests;
• if you like, a recording of the Simulator or Android screen while it happened.

Save the bundle as a .zip, or file it as an issue in GitHub, Jira or Linear with your own token. Nothing leaves your Mac until you click File.

12345

Describe the bug on the left; the right shows exactly what goes in the bundle.

1. Your description
2. Which requests
3. The summary that gets filed
4. Every file in the bundle
5. Save or file

×

Open Report Bug

Where	Which requests
Select requests, right-click and choose Report Bug… (or Report Bug with N Requests…)	The selected requests
Tools › Report Bug… (⇧ ⌥ ⌘ B)	The selected requests, or, with none selected, the last five minutes of the app in the sidebar

In the window, under Requests, switch between the selection and Recent: the last 1 to 60 minutes of one app or every app. Recent requests keep coming in while the window is open, so you can reproduce the bug with the window already set up.

Write the report

1. Give it a Title. If the requests include a failure, Cloak Proxy suggests one, such as POST /v2/checkout fails with 502.
2. Fill in What happened, Steps to reproduce and Expected. Leave any of them empty and they’re left out.
3. Choose what to include (see What’s in the bundle). Leave Redact tokens, cookies, passwords and keys on unless everyone who’ll read the report may see them.
4. Optionally, record the screen while you reproduce the bug.
5. Check the summary on the right. It updates as you type and as requests arrive. Copy Summary copies the Markdown.
6. Save it or file it.

What’s in the bundle

The bundle is a .zip with one folder named after the title:

• Directorycheckout-fails-with-502/

  • README.md
  • requests.har
  • requests.cloaksession
  • Directoryreplay/

    • collection.json
    • flow.json
  • reproduce.sh
  • browser-console.json
  • screen-recording.mp4

File	What it is	Switch
README.md	The summary below. It’s also the issue’s description when you file it.	Always
requests.har	Every request and response. Opens in browser dev tools, Charles, Proxyman and Cloak Proxy.	HAR file
requests.cloaksession	The same as a Cloak Proxy session, with timings and apps. Open it with File › Open Session….	Cloak Proxy session
replay/collection.json, replay/flow.json	The requests as an API-client collection and a replayable flow that carries IDs and tokens from one response to the next request.	Replayable flow for the API client
reproduce.sh	A cURL command for each failing request.	cURL commands for failing requests
browser-console.json Since 0.4.1	Console errors from your browser tabs, with their stacks, if the browser extension is paired.	Always, when there are any
screen-recording.mp4	The screen recording, if you made one.	Screen recording

The summary

README.md puts the failing requests first, because that’s what a developer reads first.

Part	What it shows
Your description	What happened, Steps to reproduce and Expected.
Facts table	The app and its version (from its User-Agent), the device for requests from an iPhone or Android device, when the requests were captured, how many failed, the hosts, which requests were included, and Cloak Proxy’s version.
Failing requests	Each request with a 4xx or 5xx status, no response, or an API contract error. For each one: when it happened (and how far into the screen recording), how long it took, the app, its trace ID with Open in … links and any broken propagation, contract errors, the Sentry error report it caused, the start of the response body (pretty-printed JSON), and a cURL command. Up to 15 are listed in full.
Sentry error reports	Error reports the app sent to Sentry that couldn’t be matched to a failing request.
Browser console Since 0.4.1	Uncaught errors and rejected promises from browser tabs, from a minute before the first request to a minute after the last, with the script and line. Up to 20. Needs the browser extension.
Timeline	Every request in order, with its time from the start (or from the start of the recording), status and duration. Failures are in bold. Up to 200 rows; the HAR has the rest.
Files	What each file in the bundle is.

Sentry error reports are matched for you

When an app sends an error to Sentry (/api/<project>/envelope/ or /store/, on sentry.io or your own Sentry), Cloak Proxy reads the error’s type and message and attaches it to the failing request the same app sent up to 30 seconds earlier. The report then shows which API call caused which crash or error.

Redaction

With Redact tokens, cookies, passwords and keys on, every file in the bundle goes through the same redaction as exports: credential headers, cookies, password and token fields, credential query parameters and anything the secret scanner recognises become REDACTED. This includes the summary, the cURL commands and Sentry messages. Turn it off only when everyone who’ll read the report may see those values; the window warns you while it’s off.

The cURL commands in a redacted report don’t work as they are: replace each REDACTED with a real value first. reproduce.sh says so at the top.

Record the screen

1. Boot the Simulator you’re testing in, or connect an Android device or emulator with USB debugging on.
2. Under Screen recording, choose it and click Start.
3. Reproduce the bug.
4. Click Stop (⌘ .). The recording is added as screen-recording.mp4, and the summary’s times now count from the start of the video, so +0:13 in the timeline is 13 seconds into the recording.

Simulators are recorded with Xcode’s simctl, and Android devices with adb screenrecord, which stops after three minutes. Remove drops the recording.

Save the bundle

With Save to Disk selected at the bottom, click Save Bundle… (⌘ S) and choose where. Cloak Proxy shows the .zip in Finder, ready to attach to an issue, an email or a chat.

File it in GitHub, Jira or Linear

Choose GitHub, Jira or Linear at the bottom. The first time, click Set Up tracker**…** and enter where to file and your token.

Each tracker is set up once. Tokens are kept in the Keychain.

×

Tracker	You enter	What filing does
GitHub	The repository (owner/name), the API address for GitHub Enterprise, labels, and a fine-grained token with Issues: Read and write	Creates an issue with the summary. GitHub can’t take attachments through its API, so drag the .zip onto the issue afterwards, or turn on Also upload the HAR as a secret gist (the token then needs the gist scope) to link the HAR from the issue.
Jira	Your site (https://example.atlassian.net), the project key, the issue type (Bug by default), labels, your account’s email and an API token	Creates the issue with the summary converted to Jira’s formatting, and attaches the .zip.
Linear	The team key (such as ENG) and a personal API key	Uploads the .zip, then creates the issue with the summary and a link to the bundle.

Then click File in GitHub, File in Jira or File in Linear (⌘ Return). When it’s done, a link to the new issue appears next to the button.

Nothing is sent without your click

Report Bug only contacts a tracker when you click File. It talks to the tracker directly, never through the proxy, and only sends the bundle you see in the window. GitHub uses the same token as Publish to Gist. Remove Token in the tracker’s sheet deletes it from the Keychain.

AI assistants and the command line

An assistant connected to the MCP server can build a bundle with make_bug_report: pick requests by id, or the last few minutes of an app, give a title and description, and it saves the .zip and returns the summary. It can’t file the report. With review: true it opens the Report Bug window filled in, so you can check it and click File yourself. See the MCP tools reference.

cloakctl report builds the same bundle from a saved session or HAR, for example from a CI recording:

Terminal

cloakctl report --har run.har --title "Checkout fails with 502" --description "Nightly UI tests" --out reports/
cloakctl report --from-app --app ShopApp --minutes 10 --title "Login loops" --out ~/Desktop/

Option	What it does
--session FILE, --har FILE	The requests to report.
--from-app	Use the running app’s captured traffic instead.
--ids 3,7,12	Only these requests.
--app NAME, --minutes N	Only one app’s requests, or the last N minutes.
--title, --description, --steps, --expected	The report’s words. --title is required.
--out FILE.zip or --out DIR	Where to write the bundle. By default, the current folder.
--no-redact, --no-har, --no-session, --no-replay, --no-curl	Leave something out.
--markdown	Print only the summary.

Limits

• A request counts as failing when it got a 4xx or 5xx, no response at all, or an API contract error. A 200 with an error in its body isn’t flagged: select it and describe it yourself.
• The bundle includes the response bodies Cloak Proxy captured, up to the body size limit in the proxy settings.
• Redaction removes credentials, not personal data such as names and emails. Check the summary before filing in a tracker people outside your team can read.
• Screen recording needs Xcode for Simulators and adb for Android. Physical iPhones can’t be recorded.

Related

RedactionWhat's removed from exports and reports.

Publish to GistShare requests as a GitHub gist.

Distributed tracingTrace IDs and links in the report.

Replayable flowsRun the bundle's flow in the API client.