@adveron/cli

Command-line client for the Adveron public API — the tenant /v1 surface, for shell scripts, cron jobs, and the bash tool inside an agent sandbox. It is a thin layer over @adveron/sdk: every command dispatches to the SDK function of the same name, and both are generated from the API's own OpenAPI document, so the CLI cannot offer a command the API does not serve.

Install

npx @adveron/cli brand search --q nike   # no install
npm i -g @adveron/cli                    # then: adveron brand search --q nike

Node 18 or newer.

Authentication

The API key is read from ADVERON_API_KEY and from nowhere else:

export ADVERON_API_KEY="your-workspace-key"
adveron balance get

There is no --key flag, and passing one is an error rather than an unknown option. A credential on a command line is written to the shell's history file and is visible in ps to every other process on the machine for as long as the call runs; an environment variable is neither.

In a Managed Agents session the key is already in the environment — the sandbox is provisioned with ADVERON_API_KEY set, so adveron commands work with no setup. The value there is an opaque placeholder that Anthropic substitutes for the real key on the way out of the sandbox, which is why the CLI never inspects the key's shape: it is sent exactly as the environment holds it.

| Variable | Meaning | | ----------------- | ----------------------------------------------------------------------------------------- | | ADVERON_API_KEY | Workspace API key. Required. Sent as Authorization: Bearer …, never in a URL or a body. | | ADVERON_API_URL | Base URL. Defaults to https://api.adveron.com. --base-url overrides it. |

Finding a command

Every command is an API operation, spelled exactly as the operation is named: brand.mentions.list is adveron brand mentions list, and brand.owned_media.posts.list is adveron brand owned-media posts list. A dot is a space, an underscore is a hyphen, nothing else changes — so a command you can run is an operation you can look up, in either direction.

Path parameters are positional arguments; query parameters are flags with the same names, and the spec's own types and enums are enforced before a request is made.

adveron --help                    # the top level: brand, audience, category, report, …
adveron brand --help              # what lives under brand, groups and operations both
adveron brand mentions --help     # the four mention reads
adveron brand mentions list --help

Output

JSON on stdout, one document per call. Failures go to stderr and never to stdout, so a redirect holds a document or nothing.

| Flag | Effect | | ---------- | ----------------------------------------------------------------------- | | --json | Accepted and ignored — JSON is the default; scripts pass it to say so. | | --pretty | Indent the JSON. | | --ndjson | One JSON document per line: a line per item on a list read. | | --all | On a paginated read, follow the cursor to the end and write every item. |

Exit codes: 0 success, 1 the call was never made (bad input, missing key), 2 the API refused it, 3 the request never reached the API. A retry is worth making on 3 and pointless on 2.

Three examples

One call.

$ adveron brand search --q nike --limit 2 --pretty
{
  "data": {
    "items": [
      { "id": "0b0c…", "name": "Nike", "slug": "nike" }
    ]
  },
  "meta": { "request_id": "req_01J…", "total": 1, "next_cursor": null }
}

A paged export to a file. --all walks the cursor; --ndjson writes a row per line, so a 300-post export streams to disk instead of being assembled in memory (or in an agent's context).

adveron brand mentions list 0b0c… \
  --q granola --start-date 2026-08-20 --limit 100 \
  --all --ndjson > mentions.ndjson

wc -l mentions.ndjson
jq -r 'select(.sentiment == "NEGATIVE") | .url' mentions.ndjson | head

An error. The API's own envelope, on stderr, with the request_id to quote in a support request:

$ adveron audience get AUD999 ; echo "exit=$?"
{"error":{"code":"resource_not_activated","message":"This workspace holds no slot on that audience.","request_id":"req_01J…"}}
exit=2

Writes

The operations that take a request body read it from --body or --body-file (- reads stdin), as JSON:

adveron brand compare --body '{"brand_ids":["0b0c…","1d2e…"]}'
jq -n '{brand_ids: $ARGS.positional}' --args 0b0c… 1d2e… | adveron brand compare --body-file -

Send --idempotency-key <value> to make a call safe to retry — recommended on metered reads, where an auto-retried call would otherwise be charged twice.

Reference

The full operation reference, with request and response shapes for every /v1 endpoint, is the API's own interactive documentation at https://api.adveron.com/v1/docs.