CLI
Document version: 20261024
Available on the macOS and Windows desktop apps. iOS and Android do not include this command. Open ApiCatcher before you use it.
CLI lets an AI use the features ApiCatcher already has, such as searching and analyzing HTTP requests, and managing scripts and rewrite rules.
Where the command is
Run it in the system terminal. On macOS that is Terminal. On Windows that is Command Prompt or PowerShell.
On macOS the command is inside the installed app:
/Applications/ApiCatcher.app/Contents/MacOS/apicatcher-cli tools
If ApiCatcher is not in the Applications folder, replace /Applications/ApiCatcher.app with the location of your ApiCatcher.app.
You can give it a short name in the current terminal window, then type apicatcher:
alias apicatcher="/Applications/ApiCatcher.app/Contents/MacOS/apicatcher-cli"
On Windows, open the folder where ApiCatcher is installed and run apicatcher-cli.exe. The usual location is:
%LOCALAPPDATA%\Programs\ApiCatcher\apicatcher-cli.exe tools
The ApiCatcher icon on the desktop opens the window. It is not this command.
The examples below say apicatcher. Use the full path on your computer instead.
The app has to be open, with CLI turned on
CLI is off by default and does not bind a port. To use the command:
- Open ApiCatcher.
- Open CLI in the sidebar and turn the switch on.
- Quit the app completely and open it again. That launch is the one that accepts commands on this computer.
Turning the switch off also waits until the next launch.
The command fails when the app is closed, the switch is off, or you have not restarted since changing the switch.
Commands
List the tools and parameters for this version. Use that output as the schema. Do not keep a handwritten copy of the parameters.
apicatcher tools
Call one tool. --args is a JSON object.
apicatcher call search_requests --args '{"host":"api.example.com","limit":10}'
You can also pass the object on standard input:
printf '%s' '{"host":"api.example.com"}' | apicatcher call search_requests
When --args is omitted and stdin is a terminal, the arguments are {}. Tools that take no arguments can be called directly:
apicatcher call get_capture_status
Help:
apicatcher --help
Output
Stdout is a single JSON object. ok says whether it succeeded.
On success, a JSON tool result is embedded in result. Any other tool result stays a string.
{"ok":true,"tool":"search_requests","result":[{"id":"...","url":"https://api.example.com/v1/users","method":"GET","status":200}]}
On failure:
{"ok":false,"error":"ApiCatcher is not running"}
Tools you will use most
| Tool | What it does |
|---|---|
get_capture_status | Whether capture is running, the current session, and the request count |
start_capture / stop_capture | Start or stop capture |
list_capture_sessions | List capture sessions, newest first |
search_requests | Search requests by host, method, status code, or keyword |
get_request_detail | HAR detail for one request id |
export_curl | Export one request as a cURL command |
host_list | List captured hosts |
api_list | List recognized endpoints for one host |
search_logs | Search system and script logs |
get_filter_rules / set_filter_rules / delete_filter_rule | Read or change the host blocklist and allowlist |
list_scripts / get_script_docs / create_script / update_script / delete_script | Manage scripts. Call get_script_docs before writing a script |
list_rewrite_rules / create_rewrite_rule / update_rewrite_rule / delete_rewrite_rule | Manage rewrite rules |
list_dns_rules / create_dns_rule / delete_dns_rule | Manage DNS mappings |
list_tasks / create_task / get_task_results | Manage scheduled tasks and read their history |
replay_request | Replay a captured request, with optional parameter, header, or body changes |
export_api | Export endpoints to Postman or Apifox |
clear_history / clear_hosts | Clear captured history, or clear host and endpoint records |
sleep | Wait a number of seconds. Use this when the user still needs to trigger a request |
Common search_requests fields:
| Field | Meaning |
|---|---|
keyword | Search text |
search_target | url, host, req_header, resp_header, req_body, resp_body |
method | For example GET or POST |
host | Host name |
status_code | HTTP status code |
file_type | all, json, html, image, video, js, css, text |
session_id | Value from list_capture_sessions or get_capture_status, passed back unchanged |
limit | Maximum rows. Default 20 |
skip | Rows to skip, for paging |
Example
Search for requests, then load the detail of one result:
apicatcher call search_requests --args '{"host":"api.example.com","limit":5}'
apicatcher call get_request_detail --args '{"request_id":"paste the id from the previous result"}'
Security
- The command works only on this computer. Other devices on the network cannot reach it.
- Command output is real captured traffic and may include cookies, tokens, and bodies. Do not post it in public.