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.
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.
Running the CLI
From the AgentRef repository:
Or via npm:
Authentication
The CLI resolves credentials in this order:
--api-key flag (highest priority)AGENTREF_API_KEY environment variable~/.agentref/config.json file
Config File
Store persistent configuration at ~/.agentref/config.json:
{
"baseUrl": "https://www.agentref.dev/api/v1",
"apiKey": "ak_live_your_api_key_here",
"updatedAt": "2026-03-23T10:00:00Z"
}
Create API keys in the AgentRef dashboard under Settings > API Keys. Keys are shown only once — store them securely.
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:
{
"ok": true,
"command": "programs list",
"transport": "rest",
"data": { ... },
"meta": { ... }
}
jq or other automation tools.
Commands
whoami
Display the authenticated user identity.
Show full merchant account details.
programs list
List your affiliate programs.
agentref programs list
agentref programs list --limit 5 --page 2
agentref programs list --json
| Flag | Description |
|---|
--limit <n> | Number of programs per page |
--page <n> | Page number |
--page-size <n> | Items per page |
--offset <n> | Offset-based pagination |
programs create
Create a new affiliate program.
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 |
create_program API parameters (cookie duration, payout threshold, etc.).
marketplace list
Browse the public marketplace catalog.
agentref marketplace list
agentref marketplace list --via mcp
| Flag | Description |
|---|
--via <rest|mcp> | Transport layer to use (default: rest) |
| Standard filter flags | Category, min commission, etc. |
--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
agentref whoami --json
if [ $? -eq 4 ]; then
echo "API key is invalid or expired"
exit 1
fi
Examples
Quick status check
# 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
#!/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
.github/workflows/setup-program.yml
- 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
For more complex automation workflows, consider using the Node.js SDK or Python SDK instead. The CLI is best for quick operations and shell scripting. 
