> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safefetch.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Install and use the SafeFetch CLI to send, inspect, and manage actions from the terminal.

## Install

```bash theme={null}
npm install -g @safefetch/cli
```

Or run without installing:

```bash theme={null}
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

```bash theme={null}
export SAFEFETCH_API_KEY=sf_live_...
export SAFEFETCH_API_URL=https://api.safefetch.dev   # optional, this is the default
```

### `.safefetch` config file

```ini theme={null}
SAFEFETCH_API_KEY=sf_live_...
SAFEFETCH_API_URL=https://api.safefetch.dev
```

### Per-command flag override

```bash theme={null}
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:

```bash theme={null}
safefetch send --url https://example.com/api/notify
```

Send with a JSON body and retries:

```bash theme={null}
safefetch send \
  --url https://example.com/api/notify \
  --body '{"user_id":"u_123","event":"signup"}' \
  --retries 5
```

Require human approval before delivery:

```bash theme={null}
safefetch send \
  --url https://example.com/api/delete-account \
  --body '{"user_id":"u_123"}' \
  --approve
```

Wait for the result synchronously:

```bash theme={null}
safefetch send \
  --url https://example.com/api/notify \
  --sync
```

Prevent duplicate actions with a deduplication key:

```bash theme={null}
safefetch send \
  --url https://example.com/api/notify \
  --dedupe order_456
```

Use an idempotency key to safely retry the request:

```bash theme={null}
safefetch send \
  --url https://example.com/api/notify \
  --idempotency-key req_789
```

***

### `get`

Retrieve a single action by its ID.

```bash theme={null}
safefetch get <act_id>
```

**Example:**

```bash theme={null}
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:

```bash theme={null}
safefetch list
```

List failed actions:

```bash theme={null}
safefetch list --status failed
```

Paginate through results:

```bash theme={null}
safefetch list --limit 50 --offset 50
```

***

### `approve`

Approve an action that is waiting for human approval.

```bash theme={null}
safefetch approve <act_id>
```

**Example:**

```bash theme={null}
safefetch approve act_V1StGXR8_Z5j
```

***

### `cancel`

Cancel a `pending` or `awaiting_approval` action.

```bash theme={null}
safefetch cancel <act_id>
```

**Example:**

```bash theme={null}
safefetch cancel act_V1StGXR8_Z5j
```

***

### `retry`

Retry a `failed` or `cancelled` action.

```bash theme={null}
safefetch retry <act_id>
```

**Example:**

```bash theme={null}
safefetch retry act_V1StGXR8_Z5j
```

***

### `health`

Check that the SafeFetch API is reachable.

```bash theme={null}
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.