CLI
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.
Prefer a UI? Use the dashboard quickstart 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:
npx affitor login
npx affitor initlogin 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. 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.
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.
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.
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.For project-scoped MCP configuration in Claude Code, Cursor, or Codex, follow Set up a coding agent. 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>:
<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:
window.affitor.signup("user_123", "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. 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:
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 and Track Sale.
Step 5 -- Test Your Integration
Send test events to verify your integration:
npx affitor test click
npx affitor test lead
npx affitor test saleThen check your program health:
npx affitor statusNon-Interactive Mode
For CI/CD and AI agents, pass --no-interactive --json to skip prompts and get machine-readable output:
npx affitor init \
--name "My SaaS" \
--domain example.com \
--commission-type recurring_percent \
--commission-rate 30 \
--duration-months 12 \
--cookie-duration 90 \
--no-interactive \
--jsonThe 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).
Output is valid JSON, ready for AI agents to parse:
{
"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"
}
}- Running
npx affitor initin 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 initcreates a new program; it never replaces a key.