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 documented tool surface follows the existing SDK source. It does not yet expose the new event identity, event readiness, record deletion polling, or workflow history cursor operations. Older tool results also use earlier event and deletion types. Use the current REST reference for those flows and read the client compatibility table before automating writes. Tool success alone does not establish event readiness, finished erasure, or downstream delivery.

Install

Requires Node.js 18 or later.

npm install -g maxclicks-cli
# or run without installing:
npx maxclicks-cli whoami

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 check the current API reference when an operation is not available in the CLI.

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

Four source commands expose --idempotency-key for retaining the same logical write across retries: records create, records upsert, suppressions batch-add, and suppressions batch-remove. Reusing a key returns the original result instead of writing again. The current API supports 17 keyed writes, including template send, workflow trigger, webhook changes, and broadcast updates. The CLI does not expose a key flag for the remaining operations; use direct HTTP when replay protection is needed. 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

The CLI is the intended interface for AI agents: one authenticated command per action, JSON in and JSON out, exit codes on failure.

• 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