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.

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:

./bin/agentref help

Or via npm:

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:

~/.agentref/config.json

{
  "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.

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": {
    "programs": []
  },
  "meta": {
    "page": 1,
    "limit": 20
  }
}

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

Commands

whoami

Display the authenticated user identity.

agentref whoami

merchant me

Show full merchant account details.

agentref merchant me
agentref me              # alias

merchant programs list

List your affiliate programs.

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.

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.

agentref affiliate me

affiliate overview

Show aggregate affiliate performance across joined programs.

agentref affiliate overview

affiliate programs list

List programs joined by the current affiliate account.

agentref affiliate programs list

affiliate programs get

Load one joined program context.

agentref affiliate programs get --program-id PROGRAM_ID

affiliate marketplace list

Browse the public marketplace catalog.

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

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.