cloakctl command-line tool

cloakctl is the command-line tool that ships inside Cloak Proxy. It does three jobs: it talks to the running app (list, show, replay and export captured requests), it runs a capture proxy on its own with no app window (for scripts and CI), and it runs the API client workspace from Terminal, like Newman or the Postman CLI. It is also the MCP server that AI assistants use.

Put cloakctl on your PATH

The tool lives inside the app bundle at:

/Applications/Cloak Proxy.app/Contents/Resources/cloakctl

You can run it from there, but a link on your PATH lets you type cloakctl. The app shows the exact path and a ready-made command in Settings › Advanced › Command line.

123

Settings › Advanced shows where cloakctl is and copies the commands that link it and connect AI assistants.

1. Where cloakctl is on this Mac
2. Copies the command that links cloakctl into /usr/local/bin
3. Copies the command that adds the MCP server to Claude Code

×

1. Open Settings › Advanced and click Copy next to Link to /usr/local/bin.

2. Paste the command into Terminal and press Return. macOS asks for your password because /usr/local/bin belongs to the system.

   Terminal

   sudo mkdir -p /usr/local/bin
   sudo ln -sf "/Applications/Cloak Proxy.app/Contents/Resources/cloakctl" /usr/local/bin/cloakctl

   The first line only matters on a Mac where /usr/local/bin doesn’t exist yet.

3. Check that it works:

   Terminal

   cloakctl status

The link points into the app, so it keeps working after you update Cloak Proxy. Remove it with sudo rm /usr/local/bin/cloakctl.

Tip

Run cloakctl with no arguments (or an unknown command) to print the built-in usage text.

Commands at a glance

Command	What it does	Needs the app running
cloakctl run	Runs a headless capture proxy and prints each exchange. Can record, report and fail a CI job.	No
cloakctl ca	Prints the path of the root certificate, creating it if needed.	No
cloakctl status	Port, request count and active debugging tools.	Yes, or cloakctl run
cloakctl list	Captured requests, one per line.	Yes, or cloakctl run
cloakctl show ID	Headers and bodies of one request, as JSON.	Yes, or cloakctl run
cloakctl curl ID	One request as a cURL command.	Yes, or cloakctl run
cloakctl replay ID	Sends a captured request again.	Yes, or cloakctl run
cloakctl export	Every captured request as HAR.	Yes, or cloakctl run
cloakctl mcp	The Model Context Protocol server, on standard input and output.	For traffic and proxy tools
cloakctl collection list	Collections, requests and environments in the workspace.	No
cloakctl collection run	Runs a collection with its tests and reporters.	No
cloakctl mock	Serves a collection’s saved examples on localhost.	No
cloakctl perf	Load tests a collection.	No
cloakctl spec	Lints, imports and syncs OpenAPI specs.	No
cloakctl docs	Writes a collection’s API documentation as one HTML file.	No

Run a headless proxy

cloakctl run starts a capture proxy without the app. It uses the same engine, the same root certificate and the same debugging-tool rules format as the app, and prints one line per finished request. Use it on a Mac where you don’t want the app open, in scripts, or to wrap a test command in CI. The CI options are covered in depth in Headless runs and CI.

Terminal

cloakctl run --port 9091 --ssl 'api.example.com' --ssl '*.example.com'

On start it writes the listening address and the certificate path to standard error:

Cloak Proxy listening on 127.0.0.1:9091
CA: /Users/ada/Library/Application Support/CloakProxy/cloak-proxy-ca.pem

Proxy options

Flag	Value	What it does
--port	Number	Port to listen on. Default 9090. Pick another port, such as 9091, while the app is running on 9090.
--ssl	Host pattern	Decrypts HTTPS for hosts matching the pattern. Repeat for several. Wildcards work: *.example.com, or '*' for everything. Without it, HTTPS passes through as encrypted tunnels.
--ssl-app	App name	Decrypts every HTTPS connection from that app. Repeat for several.
--tools	Path to a JSON file	Loads debugging-tool rules, and which tools are on, from a file made with Tools › Export Rules… (Map Local, Map Remote, Scripting, Block List and the rest).
--keylog	Path	Writes TLS session keys in SSLKEYLOGFILE format for Wireshark.
--all-interfaces	None	Listens on 0.0.0.0 so other devices can connect. By default it listens on 127.0.0.1 only.

Recording and CI options

Flag	Value	What it does
--record	Path	Saves the traffic when the run ends: HAR if the file ends in .har, otherwise a Cloak Proxy session (.cloaksession).
--redact	None	Removes tokens, cookies, passwords and keys from the recording.
--report	Path	Writes a Markdown report: endpoints with calls, errors, p50 and p95; possible secrets (masked); security header grades; performance findings; and schema changes.
--mock	Path to a .har or .cloaksession	Answers requests from a recording instead of the network, for offline tests. Unrecorded requests to a recorded host get a 404.
--duration	Seconds	Stops after this long.
--quiet	None	Doesn’t print each request.
--fail-on-5xx	None	Exits with 1 if any response was a server error.
--fail-on-error	None	Exits with 1 on any 4xx, 5xx or failed request.
--fail-on-secrets	None	Exits with 1 if high-severity secrets were found.
--fail-on-schema-change	None	Exits with 1 if an endpoint’s JSON shape changed during the run.
--	A command and its arguments	Runs the command with the proxy and certificate environment set, and stops the proxy when it exits. Must come last.

The run stops on Control C, on SIGTERM, after --duration, or when the command after -- exits. Then it writes the recording and the report, and prints a one-line summary to standard error:

42 requests, 9 endpoints, 1 errors, 0 possible secrets, 0 schema changes

What each output line shows

Each finished request prints as one line:

Part	Example	Meaning
Id	#12	The request’s number in this run.
App	[node]	The app that sent it, or ? when it can’t be identified.
Status	200, TUN, ERR	The response status, TUN for an HTTPS connection passed through without decrypting, or ERR for a failure.
Method and URL	GET https://api.example.com/v1/users	The request.
Duration and size	84ms 2 KB	Time to complete and response body size.

Decrypted requests end with a lock symbol. Failed requests print the error message on an indented second line.

Print the certificate path

Terminal

cloakctl ca

Prints the path of the Cloak Proxy root certificate (~/Library/Application Support/CloakProxy/cloak-proxy-ca.pem). If no certificate exists yet, it creates one first. Use it to point a runtime at the certificate, for example export NODE_EXTRA_CA_CERTS="$(cloakctl ca)".

Read traffic from the running app

These commands ask the running app (or a running cloakctl run) for what it captured, through the local control API. They find the app’s port in its saved settings. If the proxy listens somewhere else, add --port N.

Terminal

cloakctl status
cloakctl list --host api.example.com --errors --limit 20
cloakctl show 12
cloakctl curl 12
cloakctl replay 12
cloakctl export --out session.har

Command	Options	Output
cloakctl status	--port N	JSON: app, port, recording, flowCount and activeTools.
cloakctl list	--search TEXT (URL or app name contains it), --host HOST (host contains it), --errors (only failures and 4xx/5xx), --limit N (default 50), --port N	One line per request, newest last: #12 200 GET [Safari] https://api.example.com/v1/users 84ms. Tunnels show TUN, failures ERR.
cloakctl show ID	--port N	Pretty JSON with the summary fields, request and response headers and bodies, and WebSocket messages.
cloakctl curl ID	--port N	The request as a curl command.
cloakctl replay ID	--port N	Sends the request again, unchanged, through the proxy, and prints the new request and response as JSON. The replay also appears in the app.
cloakctl export	--out FILE, --port N	Every request the proxy remembers, as HAR. Without --out it writes to standard output.

These commands see the proxy engine’s own list of the most recent 5,000 requests. That list starts empty each time the proxy restarts, isn’t emptied by Clear Session, and doesn’t include sessions you open from files.

Exports contain secrets

cloakctl export and cloakctl show print cookies, tokens and bodies exactly as captured. Treat the output like a password file. To share traffic, export from the app with Redact secrets turned on, or record with cloakctl run --redact. See Redaction.

If the app isn’t running, these commands stop with:

error: Couldn't reach Cloak Proxy on port 9090. Is the app (or `cloakctl run`) running? (…)

Start the MCP server

Terminal

cloakctl mcp

Starts a Model Context Protocol server on standard input and output. You don’t run this yourself; your AI assistant starts it. It accepts two options:

Flag	What it does
--port N	Talks to a proxy on this port instead of the app’s configured one.
--workspace DIR	Uses this API-client workspace folder instead of the app’s.

Setup for Claude Code, Claude Desktop, Cursor and VS Code is on MCP server.

Run the API client workspace

The workspace commands read and write the API client’s workspace folder directly, so they work without the app. If the app is open, it picks up changes.

Each command looks for the workspace in this order:

1. The folder given with --workspace DIR.
2. The folder chosen in the app’s API client.
3. ~/Library/Application Support/CloakProxy/Workspace.

Where a command takes a collection, you can pass its name, its id, or the path to a Postman collection or OpenAPI file. See Workspace and Git for the folder layout.

List collections

Terminal

cloakctl collection list --workspace ~/code/shop-api

Prints each collection with its request count and id, then each request’s method (or protocol), folder path and URL, then the names of the environments.

Run a collection

cloakctl collection run runs a collection with its scripts, tests, auth and variables, like Newman. It runs every request type the API client has: HTTP, GraphQL, gRPC, MCP, AI, SQL, WebSocket, Socket.IO, MQTT and TCP. See Collection runner for how runs work.

Terminal

cloakctl collection run "Shop API" -e Staging -d users.csv -n 1 \
  -r cli,junit --reporter-junit-export results/api.xml

Flag	Value	What it does
-e, --environment	Environment name, or a Postman environment .json file	The environment to use. Default: the workspace’s active environment.
-g, --globals	Postman globals .json file	Globals to use instead of the workspace’s.
-d, --iteration-data	.csv or .json file, or a dataset name	One iteration per row. Columns become variables. See Datasets and data files.
-n, --iteration-count	Number	How many times to run. Default 1.
--folder	Folder name	Runs only that folder (found at any depth).
--delay-request	Milliseconds	Pause between requests. Default 0.
--bail	None	Stops at the first request that errors or has a failing test.
--timeout-request	Milliseconds	Timeout for every request, overriding each request’s own setting.
--insecure, -k	None	Doesn’t verify TLS certificates for any request.
--env-var	KEY=VALUE	Adds a variable to the environment. Repeat for several. With no environment, creates one named CLI.
-r, --reporters	Comma-separated list: cli, json, junit, html	Which reports to produce. Default cli.
--reporter-json-export	Path	Where the JSON report goes. Default cloak-run.json.
--reporter-junit-export	Path	Where the JUnit XML report goes. Default cloak-run.xml.
--reporter-html-export	Path	Where the HTML report goes. Default cloak-run.html.
--workspace	Folder	The workspace to use.

The cli reporter prints each request’s folder path, method, URL, status, size and time, then a check mark or cross per test, console output, and script errors. It ends with a summary:

requests 12 (0 failed) · tests 31 (1 failed) · avg response 142ms · total 2310ms

The command exits with 0 when every request and test passed, and 1 otherwise.

Serve mocks

Terminal

cloakctl mock "Shop API" --port 4010

Serves the collection’s saved examples on http://localhost:4010 until you press Control C. Without --port, it picks a free port and prints it. Each call prints as GET /v1/users → 200 (Example name), or (no example) when nothing matched. Variables come from the active environment. See Mock servers.

Load test

Terminal

cloakctl perf "Shop API" --vus 20 --duration 60 --profile rampUp -e Staging

Flag	Value	What it does
--vus	Number	Virtual users. Default 10.
--duration	Seconds	How long to run. Default 30.
--profile	fixed, rampUp, spike or peak	Load shape. Default fixed.
--think-time	Milliseconds	Pause between each user’s iterations. Default 0.
-e	Environment name or file	The environment to use.
--workspace	Folder	The workspace to use.

It prints one line per second (active users, requests per second, average and p95 latency, errors), then totals with p90, p95 and p99 and a line per request. It exits with 1 if any request failed. See Load testing.

Work with OpenAPI specs

Command	What it does	Exit code
cloakctl spec lint FILE.yaml	Checks a spec and prints each problem with its severity, rule, message and location.	1 if any problem is an error
cloakctl spec import FILE.yaml	Adds the spec to the workspace with a linked collection generated from it.	0
cloakctl spec sync FILE.yaml	Updates the workspace spec with the same title from the file, then syncs its linked collection. Add --spec NAME when the names differ.	0
cloakctl spec sync SPEC_NAME	Syncs a workspace spec’s linked collection without changing the spec.	0

Sync keeps your tests, scripts, auth and examples, and prints each added (+), updated (~) and removed (-) request. All three accept --workspace DIR except lint. See Specs.

Generate documentation

Terminal

cloakctl docs "Shop API" --out shop-api-docs.html

Writes the collection’s documentation as one self-contained HTML file, with the active environment’s values. See Generate docs, SDKs and MCP servers.

Exit codes

Command	0	1	Other
run	No --fail-on-… check failed and the wrapped command (if any) succeeded	A --fail-on-… check failed, or an option was wrong	The wrapped command’s own exit code; 127 if it couldn’t start
collection run	Every request and test passed	A request or test failed
perf	No request failed	Any request failed
spec lint	No errors (warnings are fine)	At least one error
Any command		Any error, printed as error: … on standard error

Commands the app runs for you

The app starts some cloakctl commands itself. You don’t need them, but you may see them in Activity Monitor.

Command	What it’s for
cloakctl proxy-guard --pid PID --port PORT	Started while the macOS proxy points at Cloak Proxy. If the app disappears without quitting (Force Quit, crash), it restores your previous proxy settings so the Mac stays online. --dry-run only reports what it would do.
cloakctl dns-standby	Started at login by a LaunchAgent while you capture apps that ignore the proxy. When the app isn’t running, it answers DNS lookups for captured domains normally.
cloakctl bypass-scan [--port N]	Lists apps connecting straight to the internet instead of through the proxy on that port (default 9090), with their direct connections. The app’s Not Using the Proxy list uses the same scan.
cloakctl render-icon --out DIR	Builds the app icon. Used when building the app.

Related

Headless runs and CIRecord, check and mock API traffic in CI with cloakctl run.

Control APIThe local REST API cloakctl talks to.

MCP serverLet Claude, Cursor and other assistants drive Cloak Proxy.

Run API tests in CIA step-by-step guide with JUnit results.