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

# CLI

> The AgentRef CLI is a thin, automation-friendly command-line interface for managing affiliate programs, listing marketplace offerings, and querying account information.

The `agentref` CLI is a lightweight command-line tool that wraps the AgentRef REST API v1 and MCP server. It is designed for scripting, CI/CD pipelines, and quick account operations from the terminal.

<Note>
  The CLI reuses existing AgentRef surfaces -- REST API v1 for account/program operations and MCP for marketplace access. It does not duplicate business logic; all domain logic stays on the server.
</Note>

## Running the CLI

From the AgentRef repository:

```bash theme={null}
./bin/agentref help
```

Or via npm:

```bash theme={null}
npm run agentref -- help
```

## Authentication

The CLI resolves credentials in this order:

1. `--api-key` flag (highest priority)
2. `AGENTREF_API_KEY` environment variable
3. `~/.agentref/config.json` file

### Config File

Store persistent configuration at `~/.agentref/config.json`:

```json title="~/.agentref/config.json" theme={null}
{
  "baseUrl": "https://www.agentref.co",
  "apiKey": "ak_live_your_api_key_here",
  "updatedAt": "2026-03-23T10:00:00Z"
}
```

If no `--base-url`, `AGENTREF_API_BASE_URL`, saved config, or `NEXT_PUBLIC_APP_URL` is present, the local development CLI falls back to `http://localhost:3000`.

<Warning>
  Create API keys in the AgentRef dashboard under **Settings > API Keys**. Keys are shown only once -- store them securely.
</Warning>

## Global Options

Every command accepts these flags:

| Flag                | Description                             |
| ------------------- | --------------------------------------- |
| `--json`            | Stable machine-readable output envelope |
| `--base-url <url>`  | Override API base URL                   |
| `--api-key <key>`   | Override stored API key                 |
| `--timeout-ms <ms>` | Request timeout in milliseconds         |
| `--retries <n>`     | Retry count for retryable failures      |

### JSON Output

When `--json` is passed, all commands return a consistent envelope:

```json theme={null}
{
  "ok": true,
  "command": "programs list",
  "transport": "rest",
  "data": {
    "programs": []
  },
  "meta": {
    "page": 1,
    "limit": 20
  }
}
```

This is useful for piping into `jq` or other automation tools.

## Commands

### `whoami`

Display the authenticated user identity.

```bash theme={null}
agentref whoami
```

### `merchant me`

Show full merchant account details.

```bash theme={null}
agentref merchant me
agentref me              # alias
```

### `merchant programs list`

List your affiliate programs.

```bash theme={null}
agentref merchant programs list
agentref merchant programs list --limit 5 --page 2
agentref merchant programs list --json
agentref programs list              # alias
```

| Flag              | Description                 |
| ----------------- | --------------------------- |
| `--limit <n>`     | Number of programs per page |
| `--page <n>`      | Page number                 |
| `--page-size <n>` | Items per page              |
| `--offset <n>`    | Offset-based pagination     |

### `merchant programs create`

Create a new affiliate program.

```bash theme={null}
agentref merchant programs create \
  --name "Acme Referrals" \
  --commission-type recurring \
  --commission-percent 25

agentref programs create \
  --name "Acme Referrals" \
  --commission-type recurring \
  --commission-percent 25
```

| Flag                           | Required | Description                                     |
| ------------------------------ | -------- | ----------------------------------------------- |
| `--name <name>`                | Yes      | Program name                                    |
| `--commission-type <type>`     | Yes      | `one_time`, `recurring`, or `recurring_limited` |
| `--commission-percent <1-100>` | Yes      | Commission percentage                           |

Additional optional flags match the `create_program` API parameters (cookie duration, payout threshold, etc.).

### `affiliate me`

Show the current affiliate workspace identity.

```bash theme={null}
agentref affiliate me
```

### `affiliate overview`

Show aggregate affiliate performance across joined programs.

```bash theme={null}
agentref affiliate overview
```

### `affiliate programs list`

List programs joined by the current affiliate account.

```bash theme={null}
agentref affiliate programs list
```

### `affiliate programs get`

Load one joined program context.

```bash theme={null}
agentref affiliate programs get --program-id PROGRAM_ID
```

### `affiliate marketplace list`

Browse the public marketplace catalog.

```bash theme={null}
agentref affiliate marketplace list
agentref affiliate marketplace list --via mcp
agentref marketplace list              # alias
```

| Flag                  | Description                              |
| --------------------- | ---------------------------------------- |
| `--via <rest\|mcp>`   | Transport layer to use (default: `rest`) |
| Standard filter flags | Category, min commission, etc.           |

The `--via mcp` option routes the request through the MCP endpoint instead of REST, which can be useful for testing MCP connectivity.

## Exit Codes

The CLI uses structured exit codes for scripting:

| Code | Meaning                                       |
| ---- | --------------------------------------------- |
| `0`  | Success                                       |
| `1`  | Unknown / unexpected error                    |
| `2`  | Usage error (invalid arguments)               |
| `3`  | Config error (missing config file or API key) |
| `4`  | Auth error (401 / 403)                        |
| `5`  | Rate limited (429)                            |
| `6`  | Network / timeout error                       |
| `7`  | Server error (5xx)                            |
| `8`  | API / MCP contract or client error            |

### Scripting with Exit Codes

```bash theme={null}
agentref whoami --json
if [ $? -eq 4 ]; then
  echo "API key is invalid or expired"
  exit 1
fi
```

## Examples

### Quick status check

```bash theme={null}
# Verify credentials work
agentref whoami

# List programs as JSON for parsing
agentref programs list --json | jq '.data[] | {name, status}'
```

### Create a program from a script

```bash theme={null}
#!/bin/bash
set -e

export AGENTREF_API_KEY="ak_live_..."

agentref programs create \
  --name "Q1 Referral Program" \
  --commission-type one_time \
  --commission-percent 15 \
  --json

echo "Program created successfully"
```

### CI/CD integration

```yaml title=".github/workflows/setup-program.yml" theme={null}
- name: Create affiliate program
  env:
    AGENTREF_API_KEY: ${{ secrets.AGENTREF_API_KEY }}
  run: |
    agentref programs create \
      --name "Production Referrals" \
      --commission-type recurring \
      --commission-percent 20 \
      --json
```

<Tip>
  For more complex automation workflows, consider using the [Node.js SDK](/agent-integration/node-sdk) or [Python SDK](/agent-integration/python-sdk) instead. The CLI is best for quick operations and shell scripting.
</Tip>