Command line (CLI)

flow-affiliate does from a terminal what you do in the dashboard: add apps, set store links and your own link domain, create server keys for test and production, name your events, send signed test events, upload logos and material, and set payouts. It signs in with a personal token and acts as you, within your role. That also makes it a simple way to let a coding assistant such as Claude Code do the setup: it runs the same commands, with --json.

1. Install#

   You need Node.js 20 or later.

   npm install -g https://affiliate.yflow.io/downloads/flow-affiliate.tgz
   flow-affiliate --help

2. Create a token#

   In the dashboard, open Settings → Security → CLI tokens, name the token (for example after the computer it is for), choose when it expires and select Create token. It starts with fg_cli_ and is shown once.

3. Sign in#

   flow-affiliate login --token fg_cli_...

   Or run flow-affiliate login and paste it, or set FLOW_AFFILIATE_TOKEN in the environment. The token is saved in ~/.config/flow-affiliate/config.json, which only you can read. If you are on more than one advertiser's team, choose one:

   flow-affiliate advertisers list
   flow-affiliate use "Example Co"
   flow-affiliate whoami

Commands#

Every command takes --help. Where an advertiser has one app or one program, the CLI uses it; otherwise pass --app or --program with its id, slug or name.

# apps and their links
flow-affiliate apps list
flow-affiliate apps create --name "Example App"
flow-affiliate apps update iosAppStoreUrl=https://apps.apple.com/app/id123456789 \
  androidPlayStoreUrl="https://play.google.com/store/apps/details?id=com.example.app" \
  trackingHost=go.example.com
flow-affiliate apps show

# the program, its setup steps and settings
flow-affiliate programs create --app example-app
flow-affiliate programs show
flow-affiliate programs set summary="Earn for every new member" attributionWindowDays=30
flow-affiliate programs submit

# server keys: the secret is printed when the key is made; the dashboard can show it again
flow-affiliate keys create --env test
flow-affiliate keys create --env production
flow-affiliate keys list
flow-affiliate keys revoke fg_test_...

# events
flow-affiliate events catalog
flow-affiliate events add --key level.completed --name "Level completed"
flow-affiliate events send --type user.registered --user user-123
flow-affiliate events list --env test

# logos and material
flow-affiliate images upload --logo ./logo.png
flow-affiliate images upload --creative ./story.png --format story --activate

# payouts, in USD
flow-affiliate payouts add --event user.registered --amount 5
flow-affiliate payouts add --event purchase.completed --percent 10 --max 20
flow-affiliate payouts budget --daily 100
flow-affiliate payouts list

flow-affiliate apps update and flow-affiliate programs set take key=value pairs; key= (empty) removes a link setting, and values that read as JSON (30, ["SE","NO"]) are taken as JSON. flow-affiliate apps update --help lists the link settings.

Test events#

flow-affiliate events send signs an event the way your backend does (HMAC-SHA256 of <timestamp>.<body>, with the x-fg-key, x-fg-timestamp and x-fg-signature headers), posts it to /v1/events through the Node SDK, and tells you what Flow did with it: processed and credited to a publisher, or not credited and why. Pass --code (a publisher's fg_ref) or --click (fg_click) to test attribution, --amount 9.99 for a purchase.

It signs with a test key: the one you give with --key and --secret (or FG_KEY_ID and FG_SECRET), else the test key the CLI saved for the app, else it creates a test key and saves it. Only test keys are accepted, and test events never pay anything.

Anything else#

flow-affiliate api calls any endpoint of the dashboard API as you and prints the JSON answer. :aid in the path is the advertiser you act on; amounts are in cents.

flow-affiliate api GET /v1/advertisers/:aid/programs
flow-affiliate api PUT /v1/advertisers/:aid/programs/<program id>/terms --data @terms.json

For scripts and AI assistants#

• --json prints the API's answer as JSON on stdout; notes go to stderr.
• Exit code 0 when it worked, 1 when Flow refused or could not be reached (the error's code is printed), 2 for a wrong command line.
• FLOW_AFFILIATE_TOKEN signs in without a config file, FLOW_AFFILIATE_ADVERTISER chooses the advertiser, FLOW_AFFILIATE_API_URL another API, FLOW_AFFILIATE_CONFIG another config file.

What a token can do#

A CLI token acts as you: it reaches every advertiser, app and program you can reach in the dashboard, and does what your role allows there. If you leave a team or your role changes, so does what the token can do. A few things are never done with a token, whatever your role, and stay in the dashboard:

• deciding money: approving, rejecting or reversing commissions, settlements, payouts or invoices, and payout details;
• deleting anything (revoking a server key is allowed);
• your sign-in and account: password, email, two-factor, sessions and CLI tokens, and changes to a team.