Debugging tools

Rule folders and sets

Since 0.4.0 Requires Cloak Proxy 0.4.0 or later.

Put Cloak Proxy rules in nested folders that turn on and off with one click, save groups of folders as named sets such as Payment declined or Empty cart, switch between them, and share them as files.

Since 0.4.0

Rules pile up: a Map Local for every screen you’re building, a breakpoint for each bug, network conditions for the checkout. Folders keep each tool’s rules in groups you can switch on and off with one click. Rule sets go further: a set is a named group of folders across tools, such as “Payment declined” (a Map Local folder that declines the card and a Network Conditions folder that slows checkout), and switching to it turns those folders on and every other set’s folders off. QA keeps one set per scenario and switches between them from the toolbar.

The Tools window on Map Local. The rule list has a Checkout folder containing a Declined card folder with one rule and an Empty cart folder that's off, an Onboarding folder that's off, and a loose rule. The sidebar's Rule Sets section lists Payment declined (selected), Empty cart and New user. — Folders in Map Local, and the rule sets in the sidebar. Rules in a folder that's off are dimmed.

Folders

Every tool with rules has folders: Breakpoint, Map Local, Map Remote, Rewrite, Scripting, Block List, Allow List, Network Conditions and Alerts.

To	Do this
Make a folder	Click the new-folder button under the rule list. With a folder selected, the new one goes inside it.
Put a rule in a folder	Drag it just under the folder’s row or between its rules, or right-click it and choose Move to Folder and the folder. Top Level takes it out.
Add a rule to a folder	Select the folder, or a rule in it, and click +. Or right-click the folder and choose New Rule in Folder.
Turn a folder off or on	Click its checkbox.
Fold or unfold it	Click the chevron.
Rename it	Select it and edit Name on the right.
Make a folder inside another	Right-click it and choose New Folder Inside.
Delete it	Right-click it and choose Delete Folder, Keep Rules (its rules move up a level) or Delete Folder and Its Rules.

A rule runs when its own checkbox is on, its tool is on, and its folder and every folder above it are on. Turning a folder off doesn’t change its rules’ checkboxes, so turning it back on brings back exactly the rules that were on. Rules in a folder that’s off, or inside one, are dimmed, and their tooltip says so. Folders don’t change the order rules run in: within a tool, rules still run top to bottom as listed.

Click the eye under the list to hide rules that are off (by their own checkbox or their folder). Folders stay visible so you can turn them back on.

Select a folder to see its editor: its name, its switch, how many rules it holds (including folders inside it), the sets it’s in, Export Folder… and Delete Folder….

Rule names

A new rule takes its name from what it matches, such as POST api.example.com/v1/orders, or api.example.com/graphql · CreateOrder when a condition names a GraphQL operation. The name follows your edits to the URL until you type a name of your own.

Rule sets

Turn on the folders that make up a scenario, in any tools.
In the Tools window’s sidebar, under Rule Sets, click Rule Set and choose New Set from Folders That Are On…. Name it, for example Payment declined.
To switch to a set later, click it in the sidebar, or choose it from Rule set in the toolbar’s tools popover (the N tools on button in the bottom bar).

Switching to a set:

turns on every folder in the set,
turns off every folder that’s in some other set,
leaves folders that aren’t in any set as they are, and
turns on the tools the set’s folders belong to.

The active set has a filled circle in the sidebar. Clicking it again, or choosing Turn Off Every Set, turns every set’s folders off. If you change one of the active set’s folders by hand, the set is no longer marked active, since it no longer describes what’s on.

The tools popover from the bottom bar: a switch for each debugging tool, and below them Rule set: Payment declined — Switch sets without opening the Tools window.

To change a set, right-click it: Switch To This Set, Update to Folders That Are On, Rename…, Export Set… or Delete Set (its folders and rules stay). To add one folder to a set, right-click the folder and choose Add to Set, or tick the set in the folder’s editor.

Export Folder… (on a folder) and Export Set… (on a set) save a rules file with just those folders, the folders inside them, their rules and, for a set, the set. Import it with Tools › Import Rules…: its rules, folders and sets are added to yours, and any with the same id replace the existing ones, so importing an updated file again doesn’t duplicate anything. The file is the same format as Tools › Export Rules…, which now includes every folder and set.

On Linux the desktop’s Save dialog asks where to put the file. Import Rules or a Set… is in the + Rule Set menu under the Tools window’s sidebar, and reads Cloak Proxy rules files and Charles settings exports.

From an AI assistant or the command line

The MCP server has two tools:

rule_folders: list, create, rename, enable, disable, move_rule, move_folder, delete (with delete_rules), export and import. Folders are named by name, by a "Checkout › Declined card" path, or by id.
rule_sets: list, create (from named folders, or from the folders that are on), activate, deactivate, delete, export and import.

upsert_rule also takes "folder" in the rule: a folder name or path, created (with its parents) if it doesn’t exist yet, or "" to put the rule at the top.

With cloakctl, against the running app:

cloakctl rules folders                       # every folder: on/off, tool, path, rules, sets
cloakctl rules set activate "Payment declined"
npm run test:e2e
cloakctl rules set off
cloakctl rules folder disable "Checkout › Declined card" --tool mapLocal
cloakctl rules export --set "Payment declined" --out payment-declined.json
cloakctl rules import payment-declined.json

cloakctl rules exits with 1 when the app isn’t running or a folder or set doesn’t exist, so a CI script stops instead of testing the wrong scenario.

Limits

DNS Spoofing, No Caching and Mock Sets have no folders. A mock set already switches on and off as a whole.
A folder belongs to one tool. A set can hold folders from any tools.
Folders can’t be dragged; use their menu to move one inside another.

Rules and matchingURL patterns, the order rules run in, export and import.

Conditions and GraphQL operationsMatch headers, body values and GraphQL operations.

Debugging toolsEvery tool and the Tools window.

cloakctlThe command-line tool.