CLI

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:

--api-key flag (highest priority)
AGENTREF_API_KEY environment variable
~/.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.

Getting Started

Merchant Guide

Agent Integration

Tracking

Integration Guides

Webhooks

For Affiliates

Resources

Running the CLI

Authentication

Config File

Global Options

JSON Output

Commands

`whoami`

`merchant me`

`merchant programs list`

`merchant programs create`

`affiliate me`

`affiliate overview`

`affiliate programs list`

`affiliate programs get`

`affiliate marketplace list`

Exit Codes

Scripting with Exit Codes

Examples

Quick status check

Create a program from a script

CI/CD integration

​Running the CLI

​Authentication

​Config File

​Global Options

​JSON Output

​Commands

​whoami

​merchant me

​merchant programs list

​merchant programs create

​affiliate me

​affiliate overview

​affiliate programs list

​affiliate programs get

​affiliate marketplace list

​Exit Codes

​Scripting with Exit Codes

​Examples

​Quick status check

​Create a program from a script

​CI/CD integration

Running the CLI

Authentication

Config File

Global Options

JSON Output

Commands

`whoami`

`merchant me`

`merchant programs list`

`merchant programs create`

`affiliate me`

`affiliate overview`

`affiliate programs list`

`affiliate programs get`

`affiliate marketplace list`

Exit Codes

Scripting with Exit Codes

Examples

Quick status check

Create a program from a script

CI/CD integration