Skip to main content

​
Install

npm install -g @safefetch/cli
Or run without installing: 
npx @safefetch/cli --help

​
Configuration

The CLI resolves credentials in this order (highest priority first):
  1. --api-key / --api-url flags on the command line
  2. SAFEFETCH_API_KEY / SAFEFETCH_API_URL environment variables
  3. A .safefetch config file in your home directory (~/.safefetch) or the current directory (./.safefetch)

​
Environment variables

export SAFEFETCH_API_KEY=sf_live_...
export SAFEFETCH_API_URL=https://api.safefetch.dev   # optional, this is the default

​
.safefetch config file

SAFEFETCH_API_KEY=sf_live_...
SAFEFETCH_API_URL=https://api.safefetch.dev

​
Per-command flag override

safefetch --api-key sf_live_... list

​
Commands

​
send

Send an action to a target URL. 
safefetch send --url <url> [options]

Options:
  --url <url>              Target URL (required)
  --method <method>        HTTP method (default: POST)
  --body <json>            JSON body as a string
  --retries <n>            Max delivery retries (default: 3)
  --dedupe <key>           Deduplication key
  --callback <url>         Callback URL called after delivery
  --approve                Require human approval before delivery
  --sync                   Wait for the action to complete and return the full result
  --idempotency-key <key>  Idempotency key
Examples: Send a basic action: 
safefetch send --url https://example.com/api/notify
Send with a JSON body and retries: 
safefetch send \
  --url https://example.com/api/notify \
  --body '{"user_id":"u_123","event":"signup"}' \
  --retries 5
Require human approval before delivery: 
safefetch send \
  --url https://example.com/api/delete-account \
  --body '{"user_id":"u_123"}' \
  --approve
Wait for the result synchronously: 
safefetch send \
  --url https://example.com/api/notify \
  --sync
Prevent duplicate actions with a deduplication key: 
safefetch send \
  --url https://example.com/api/notify \
  --dedupe order_456
Use an idempotency key to safely retry the request: 
safefetch send \
  --url https://example.com/api/notify \
  --idempotency-key req_789

​
get

Retrieve a single action by its ID. 
safefetch get <act_id>
Example: 
safefetch get act_V1StGXR8_Z5j

​
list

List actions with optional filters. 
safefetch list [options]

Options:
  --status <status>    Filter by status (pending, awaiting_approval, delivered, failed, cancelled)
  --limit <n>          Number of results (default: 20)
  --offset <n>         Pagination offset (default: 0)
Examples: List the 20 most recent actions: 
safefetch list
List failed actions: 
safefetch list --status failed
Paginate through results: 
safefetch list --limit 50 --offset 50

​
approve

Approve an action that is waiting for human approval. 
safefetch approve <act_id>
Example: 
safefetch approve act_V1StGXR8_Z5j

​
cancel

Cancel a pending or awaiting_approval action. 
safefetch cancel <act_id>
Example: 
safefetch cancel act_V1StGXR8_Z5j

​
retry

Retry a failed or cancelled action. 
safefetch retry <act_id>
Example: 
safefetch retry act_V1StGXR8_Z5j

​
health

Check that the SafeFetch API is reachable. 
safefetch health

​
Global options

These flags apply to every command and override environment/config values: 
--api-key <key>    API key (overrides SAFEFETCH_API_KEY)
--api-url <url>    API base URL (overrides SAFEFETCH_API_URL)
--version          Print the CLI version
--help             Show help

​
Output

All commands print their response as pretty-printed JSON.