---
id: "brand/cli/quickstart"
type: "doc"
url: "https://affitor.com/docs/brand/cli/quickstart"
kind: "quickstart"
updated: "2026-11-08"
---
# CLI Quickstart

> Create your affiliate program from the terminal with npx affitor, add click, signup and payment tracking, and test the integration.

Get your affiliate program running in under 5 minutes -- program creation and live tracking from your terminal. Stripe is connected in the dashboard, not the CLI.

:::tip

Prefer a UI? Use the [dashboard quickstart](/docs/brand/quickstart/create-account) instead.

:::

## Why CLI?

| | Dashboard | CLI |
|---|---|---|
| Setup time | ~15 minutes | ~5 minutes |
| Stripe | **Connect Stripe** under **Program settings** › **Payments** | Same: `affitor setup stripe` only points you there |
| AI agent compatible | No | Yes (`--json` mode) |
| Config files generated | No | Yes (`.affitor/`) |

---

## Step 1 -- Create Your Program

Sign in first, then create your program:

```bash
npx affitor login
npx affitor init
```

`login` opens your browser to sign in to Affitor. Once it confirms you are signed in, return to your terminal and follow the `init` prompts.

You'll be asked for:
- **Program name** -- your product or company name
- **Domain** -- your root domain (e.g., `example.com`)
- **Commission type** -- percentage, fixed, or recurring
- **Commission rate** -- default is 40% for recurring
- **Duration** -- how long recurring commissions last (default: 12 months)
- **Cookie window** -- attribution window in days (default: 60)

After confirming, the CLI creates your program and generates:

```
.affitor/
  AGENTS.md       -- AI agent instructions (primary, universal standard)
  config.json     -- program ID, settings
  .env            -- API key and program ID (gitignored)
  .env.example    -- the same variables, API key left empty (gitignored)
  skills.md       -- same content as AGENTS.md (backward-compat)
```

`AGENTS.md` holds your program's values (program ID, domain, commission, cookie window, API base URL), the click, signup and sale snippets, the CLI commands, and the customer ID table from [Step 4](#use-one-customer-id-everywhere). It holds no API key, so you can commit it. `init` also adds `.affitor/.env` and `.affitor/.env.*` to your `.gitignore`, which keeps `.env` and `.env.example` out of Git. Only `.env` holds the key.

:::tip[Works with any AI coding tool]

Claude Code, Cursor, GitHub Copilot, Windsurf, Aider and other AI coding tools can follow `AGENTS.md`. It sits in `.affitor/`, not your project root, so name it in your prompt, as the line below does.

:::

<AgentPrompt prompt="Read .affitor/AGENTS.md and add Affitor tracking to this app as it describes. Then run npx affitor onboard --yes and fix what it reports until it says Integration verified.">
Using an AI coding agent? Run `init` first (it needs your login), then give your agent this line in the same project. `affitor onboard` wires in the tracking it can, prints the rest for your agent, fires a test click, lead and sale, and exits with an error until the integration is verified.
</AgentPrompt>

---

For project-scoped MCP configuration in Claude Code, Cursor, or Codex, follow [Set up a coding agent](/docs/brand/cli/agent-setup). Since 0.4.5 the CLI includes a no-write preview and `doctor` for static local checks; neither proves a live connection.

## Step 2 -- Add Click Tracking

Paste the script tag from the CLI output into your site's `<head>`:

```html
<script src="https://api.affitor.com/js/affitor-tracker.js"
  data-affitor-program-id="YOUR_PROGRAM_ID">
</script>
```

Replace `YOUR_PROGRAM_ID` with the program ID from step 1.

The script auto-detects `?via=PARTNER_CODE` or `?aff=PARTNER_CODE` in URLs and stores a first-party cookie for attribution (the window set on your program, 60 days by default).

---

## Step 3 -- Track Signups

Call `signup()` when a user registers:

```javascript tab="Client-side (browser)"
window.affitor.signup("user_123", "user@example.com");
```

```bash tab="Server-side (API)"
curl -X POST https://api.affitor.com/api/v1/track/lead \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"click_id": "YOUR_TRACKED_CLICK_ID", "customer_key": "user_123", "email": "user@example.com"}'
```

By default the browser call alone is provisional; the server call settles the lead. Send the visitor's `affitor_click_id` as `click_id`: a first lead with only `customer_key` answers `400`, because the key is saved on the customer only when a lead settles. The server-side lead example that CLI 0.4.7 writes to `AGENTS.md` sends only `customer_key`, so add `click_id` as shown here.

---

## Step 4 -- Track Payments

Choose your payment tracking method: **Server-side tracking vs Stripe integration**.

### Option A: Stripe integration (automatic)

Connect Stripe in the Affitor dashboard: open the program menu, choose **Program settings**, open **Payments**, and use **Connect Stripe**. Affitor's own webhook then records sales, renewals and refunds. Add Affitor metadata to your Checkout Session so each sale is attributed; see the [Stripe integration guide](/docs/api-reference/integrations/stripe). The CLI does not connect Stripe (`affitor setup stripe` only points you to the dashboard).

### Option B: Server-side tracking (any payment provider)

Your backend calls `POST /api/v1/track/sale`:

```bash
curl -X POST https://api.affitor.com/api/v1/track/sale \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id": "inv_123", "customer_key": "user_123", "amount_cents": 4900, "currency": "USD"}'
```

### Use one customer ID everywhere

Use your internal user ID as the customer key at signup and again with each sale. Each surface names the field differently:

| Where | Field |
|---|---|
| Browser `window.affitor.signup()` | first argument (`customerKey`) |
| Lead API (`/api/v1/track/lead`) | `customer_key` |
| Sale API (`/api/v1/track/sale`) | `customer_key` |
| Stripe Checkout metadata | `affitor_customer_key` |

Full request contracts: [Track Lead](/docs/api-reference/track-lead) and [Track Sale](/docs/api-reference/track-sale).

---

## Step 5 -- Test Your Integration

Send test events to verify your integration:

```bash
npx affitor test click
npx affitor test lead
npx affitor test sale
```

Then check your program health:

```bash
npx affitor status
```

---

## Non-Interactive Mode

For CI/CD and AI agents, pass `--no-interactive --json` to skip prompts and get machine-readable output:

```bash
npx affitor init \
  --name "My SaaS" \
  --domain example.com \
  --commission-type recurring_percent \
  --commission-rate 30 \
  --duration-months 12 \
  --cookie-duration 90 \
  --no-interactive \
  --json
```

The commission flags are saved on the program, but partners are paid by the program's Default group commission: set it in the dashboard after `init` (see [CLI commands](/docs/brand/cli/commands)).

Output is valid JSON, ready for AI agents to parse:

```json
{
  "program_id": 430,
  "api_key_file": ".affitor/.env",
  "domain": "example.com",
  "status": "created",
  "tracking": {
    "script_tag": "<script src=\"...\"></script>",
    "signup_call": "window.affitor.signup(\"customer_id\", \"email\")",
    "sale_api": "POST https://api.affitor.com/api/v1/track/sale",
    "lead_api": "POST https://api.affitor.com/api/v1/track/lead"
  }
}
```

:::warning[Common mistakes]

- Running `npx affitor init` in a directory that already has `.affitor/config.json` -- delete it first or use a different directory.
- Skipping the tracking script -- the CLI creates the program but does not modify your code.
- Using an expired API key -- ask an owner or admin of the program to create or rotate a key in **Program settings › Developers › API keys**. `npx affitor init` creates a new program; it never replaces a key.

:::
