CLI

Use maxclicks from a terminal, scheduled script, or coding agent. The CLI wraps the Public API and returns JSON, so customer updates and campaign results can fit into your existing automation.

It wraps the same API as the SDKs. Use the CLI for shell and agent work, and an SDK inside application code. Like the API, it triggers, reads, and measures what you built in the app. It does not build those things for you.

Current API coverage

The CLI uses the Public API for customer records, events, prepared campaigns, workflows, and webhooks. Follow each operation’s response and status fields: an accepted request can still require event readiness checks, deletion polling, or delivery tracking.

Install

Requires Node.js 18 or later. Install the package globally to make the maxclicks command available:

npm install -g maxclicks-cli
maxclicks login
maxclicks whoami

For a single command without a global install, use npx maxclicks-cli whoami. Authenticate with maxclicks login or set MAXCLICKS_API_KEY as described below.

Authenticate

maxclicks login creates an API key for this machine by pairing through your browser.

1. Run login

   maxclicks login opens your browser to https://app.maxclicks.ai/cli/authorize. The CLI starts a loopback listener and also polls for the result.

2. Approve in the browser

   Sign in and approve the pairing. maxclicks creates a new API key and hands it back to the CLI over that loopback connection. The browser never shows you the key.

3. Key is stored

   The key is written to ~/.config/maxclicks/config.json for the active profile. Login times out after 5 minutes.

For SSH or headless hosts, pass --no-browser: the CLI prints the authorize URL and polls until you approve it elsewhere.

You can also set a key directly instead of the browser flow:

maxclicks config set-key max_...       # writes ~/.config/maxclicks/config.json
# or per invocation:
export MAXCLICKS_API_KEY=max_...
maxclicks whoami                        # confirm the key, its owner, and its space

Keys are created and revoked in the app, under a space's Settings, in Developers. See Authentication.

Configuration

The CLI looks for your key in three places, in this order: the command flag, then the environment variable, then the config file. If one is missing, it tries the next.

Environment variables: MAXCLICKS_API_KEY, MAXCLICKS_BASE_URL, MAXCLICKS_WEB_ORIGIN, MAXCLICKS_PROFILE, XDG_CONFIG_HOME.

The config file holds one entry per profile and is written with permissions 0600. Look at it with maxclicks config show (the key is masked) or find it with maxclicks config path. maxclicks logout clears the stored key for a profile. The key still works until you delete it in the app, so delete it there too if you want it revoked.

Commands

Commands are grouped by resource: maxclicks <resource> <action> [args]. Run maxclicks <command> --help for details on any command.

Every record and event belongs to a schema, so pass the schema id or slug as the first argument (events list is the one exception, covered under Pagination below). Schemas and attributes are created and configured in the app; the public API exposes their read operations. Inspect those definitions before writing records, and use the API reference for request fields and response details.

maxclicks schemas list --type contact
maxclicks attributes list students
maxclicks records upsert students --data '{"email":"[email protected]","firstName":"Ada"}'
maxclicks records get students cm7d3k9x40001qw8h2p5tvz9r
maxclicks events fire order-placed --data '{"eventId":"ord_1","amount":42}'
maxclicks templates send cm7d3kb7t0002qw8h9m4e0xls --data '{"contact":{"email":"[email protected]"}}'
maxclicks workflows trigger 7Qk2ZbN4x9LmR3vTpW8sHc0F --data '{"anything":true}'

Prefer upsert over create. Upsert matches on the record's identity, so running it twice updates one record rather than failing. create returns 409 identifier_conflict when that identity already exists.

Pagination

List commands accept --limit (1 to 200) and --offset. Pass --all to fetch every page and return one flat JSON array. schemas list also takes --type contact|object|event.

maxclicks records list students --all | jq '.[] | .email'

events list takes its event schema as --schema <schema> rather than a positional argument, and is cursor-paginated (newest first): use --cursor, --from, --to, and --limit, or --all.

Idempotency

Use --idempotency-key with records create, records upsert, records delete, templates send, broadcasts send, workflows trigger, suppressions batch-add, and suppressions batch-remove to retain the same logical write across retries. templates send and records delete always send a key: when you pass none they generate one and print it as idempotencyKey, so retry a timed-out call with that value rather than running it fresh. records delete prints the deletion operation; follow it with records deletion-status <operationId>. Reuse the key with the same request to replay its recorded result. For direct HTTP requests, send the Idempotency-Key header on supported operations. Recorded failures can replay, and unresolved operations require reconciliation. See Idempotency.

Raw requests

For anything the commands above do not cover, maxclicks api sends an authenticated request to any path under the base URL. It returns { status, body } and sends only the Authorization, Accept, and Content-Type headers, so it cannot carry an idempotency key.

maxclicks api GET /me
maxclicks api GET '/segments?limit=5'
maxclicks api POST /webhooks --data '{"url":"https://example.com/hook","trigger":"contact upserted","schemaId":"students"}'

Output

Output is always JSON on stdout. There is no human-readable mode. A single object comes back as-is. A list command returns { data, pagination, warnings }, or a flat array with --all. Errors print to stderr and exit non-zero, so set -e and agent tool runners catch them.

maxclicks whoami | jq '.space.slug'

Use inside agents

Each command produces JSON and a non-zero exit code on failure, so agents can inspect results and stop when a request fails.

• Authenticate once with maxclicks login, or inject MAXCLICKS_API_KEY into the agent's environment.
• Learn the space first: run maxclicks schemas list, then maxclicks attributes list <schema>. Records are flat, so put base fields and your own attribute keys at the top level of --data.
• Parse stdout as JSON. On a non-zero exit, read stderr for the message.
• maxclicks docs [query] returns links to the documentation, the OpenAPI spec, and llms.txt for grounding.

Related

• SDKs
• API reference
• Agent Skills