Command Reference

The CLI command reference, grouped the same way the API reference is. Each page lists its commands with the flags they take, where the values come from, and a link to the endpoint behind each one for the full body contract and response shape.

Global flags

Every command takes these. intuizi <command> --help lists a command’s own flags as well.

auth login saves the base URL beside the token, so later commands use it without the flag. A stored token is only sent to the console that minted it. With a different --base-url, a command that needs the token fails and sends nothing, while auth login mints a token for that console and makes it the one in use (see Auth). No environment variable sets the base URL.

The creates listed on Idempotency send a fresh Idempotency-Key on each run, and a retry after a 429 reuses it. When one gets no response at all, stderr prints the key it used: rerun the same command with --idempotency-key <key> and it either replays the original result or creates the resource once. Other commands ignore the flag.

--debug prints each request’s method, URL, and headers, then the response’s status, timing, headers, and size. Credentials, keys, and signed URL parameters are redacted, and bodies are never printed: --json shows the response envelope and --dry-run the body a create would send. Stdout is unchanged, so it combines with --json and --quiet.

The CLI reads two environment variables of its own:

Conventions

These hold across the command groups below, with the exceptions named here, so the pages below do not repeat them.

Flags or a file. Every create takes flags. The audience, audience estimate, Lookalike Model, activation, cohort, and schedule creates also take --file payload.json, or - for stdin, for any field the flags do not write, such as two datasets combined with an operator, the refine, crossvisitation, and cross purchase blocks, an audience’s day-part frequency analysis, a cohort’s frequency, distance, and score limits, an activation’s partner inputs, and a schedule’s activation block. On those six, a body flag given with --file is rejected rather than resolved silently. projects create and the POI category and brand creates take flags only. poi submissions create is the exception: its --file is a CSV of locations, its JSON body goes to --list (a file or -), and --name, --brand-id, --key, --update, and --remove override the same fields in that body, --update=false and --remove=false included, and stderr notes each value a flag replaces.

Names resolve on audiences create. --brand and --category take a name or an id. A name is looked up in the catalog with a case-insensitive contains match and must come down to one entry. When several come back and exactly one is labeled with the name itself, ignoring case, that one is taken, so Example Coffee resolves even though Example Coffee Reserve also matches. Otherwise zero or several is an error listing what was found, with ids to copy from, and so is an exact label on a result too long to arrive in one page. A positive number is taken as the id and sent without a catalog check. audiences estimate create resolves them the same way. --brand-all takes every match for a search instead. --provider takes ids only, checked against the dataset type’s catalog. Every other id flag takes the id alone.

The WebDomain --category resolves to the number in the id column of intuizi reference web iab-categories, which is what Create Audience takes, rather than to the IAB code in its value column. An exact IAB code or name picks its category even when others contain it, so IAB1 resolves to IAB1 rather than failing because IAB10 to IAB19 also match. See Audiences.

--dry-run prints the body the flags produce and creates nothing. The audience, audience estimate, Lookalike Model, activation, cohort, and schedule creates take it, and it is rejected with --file and with --wait. On audiences create and audiences estimate create it still resolves names and reads the signal-provider catalog, so it needs a token. The other four send nothing and need no token. Redirecting it to a file gives a starting point for the --file form.

Output. A table by default, --json for the raw envelope, and --quiet for ids alone. Commentary goes to stderr, so a pipe sees only data. The two output flags contradict each other and are rejected together, on every command. usage, cohorts preview, activations preview, and reference profile-attributes recency-limits return no ids, so they reject --quiet. Use --json there. auth, version, and completion print text and ignore either flag given alone. uploads put prints the bare upload reference rather than a table, which is also what --quiet prints. Deletes, audiences lookalike cancel, and schedules activate and deactivate print their confirmation on stderr and nothing on stdout, with or without --quiet. --dry-run prints the request body as JSON whichever flag is set: --json adds no envelope, and --quiet prints no ids.

With --json, a request that fails at the API still prints the server’s error envelope on stdout, while the error goes to stderr and the exit code is 1, so a script reads a 422’s field errors from the same place as a success. Stdout stays empty when the response is not JSON, such as a proxy’s error page, when the command fails before its own request is sent, such as on a usage error, a missing token, or a failed catalog read on audiences create, and when the file upload itself fails on uploads put. A wait that ends on a 401, 403, or 404, or gives up before any read succeeded, prints the failed read’s error envelope.

Waiting. The audience, audience estimate, Lookalike Model, activation, and cohort creates return as soon as the work is queued, and so does poi submissions create. Only audiences create, audiences estimate create, and activations create take --wait, which polls until a build reaches Completed (104) or an estimate reads completed, or either fails, bounded by --timeout (default 60m, and rejected without --wait). audiences show <id>, audiences estimate show <id>, and activations show <id> take the same flags to follow work already running, including a Lookalike Model in training. The wait keeps going through every status that means the build is still moving: 100 to 103, 105 DataStreaming, 108 Modeling, and 109 Visualizing data streams, which an audience that opts into data stream visualizations reports while it draws them, before 105 and 104. A timeout, or giving up after three failed reads in a row, leaves the build running on the server: resume with show <id> --wait rather than creating again.

Any other status ends the wait as a failure, 107 Additional Info included, and so does a Completed activation with a datastream that failed to deliver. On 107, Intuizi stopped the build because it cannot be built as defined, and it will not move again. The API read reports only Additional Info, and the reason is shown on the audience or activation in the Audience Manager. On an audience, the usual cause is a date range outside the data available for its dataset. Fix what the reason names, then create the audience or activation again (see Waiting).

An estimate’s status is a word rather than an id: pending and processing keep the wait going, completed is the one success, and blocked and failed are final and end it with exit 1, as does a status the CLI does not know (see Estimate show).

No other command waits. Follow a cohort by rereading intuizi cohorts show <id> until it reaches status 4 Completed on the cohort scale. Status 5 Not Available means the import failed, so stop there. A POI submission moves from Importing to Waiting on its own once Intuizi has read its locations, and Intuizi then reviews it. An approved submission becomes Imported, and only then do its locations appear in intuizi poi locations list. A declined one becomes Disabled. That review is not automatic, so check a submission with intuizi poi submissions show <id> rather than scripting a wait for Imported (see POI). See The Async Model.

A wait prints status changes to stderr and the last record read to stdout, whether it completes, fails, times out, or gives up. Only Completed exits 0. A failure, a timeout, and giving up all exit 1, and stderr says which. A timeout and giving up both name the show <id> --wait command that resumes the wait. A failed build, 107 included, is final, so stderr names no command to resume it. With --json stdout is always the server’s envelope, so .data[0].status.id reads the status on every outcome: a completed or failed wait rereads the record, and a wait that timed out or gave up prints the envelope it last polled, as does a failed reread (stderr then says printing the envelope as last polled). For an estimate the status is .data[0].status itself. --quiet prints the id whatever the outcome.

Reads. Most lists take --search, --page, and --per-page. The POI segment, category, and brand lists take only --search, and so does reference cohorts list. poi submissions list is not paginated and takes --search, --sort-by, and --order. webhooks list takes no flags. The catalogs under reference have their own rules, on Catalogs.

Deletes. Every delete asks for confirmation unless --yes is given. When stdin is not a terminal there is no prompt: the delete is refused and nothing is sent, and piping y in does not answer it. Scripts and CI pass --yes.

Exit codes. 0 success. 1 a failure once the command line parsed: an API error, a --wait that failed, timed out, or gave up, or a local failure such as an unreadable --file, a missing token, or a declined confirmation. 2 a usage error: an unknown command or flag, a bad value or id, missing or conflicting flags, a delete without --yes where stdin is not a terminal, or a name that matches no catalog entry or several. Nothing is created on a 2, though a name lookup or the --provider check may already have read a catalog. 130 on Ctrl-C and 143 on SIGTERM. With the npm package, intuizi is a Node launcher. A SIGTERM or SIGHUP sent to the launcher alone, as Docker, systemd, or a CI runner sends one, is passed on to the binary, so the command stops and exits 143 for a SIGTERM, as it would without the launcher.

Command groups

• auth - log in and out.
• audiences - build audiences and Lookalike Models, and estimate an audience’s size.
• activations - deliver an audience to an endpoint connection, and preview a frequency filter.
• cohorts - import your own identifiers from a file, an upload, or an audience.
• schedules - rebuild an audience on a recurring window.
• projects - the folders everything is filed under.
• poi - manage your own POI data.
• uploads - send a file to Intuizi.
• reference - read the catalogs of ids every other command needs.
• usage - data scanned in a month, and the monthly limit.
• webhooks - list registered webhook endpoints.

Two commands sit outside these groups: intuizi version prints the build version, and intuizi completion <shell> writes a shell completion script (--no-descriptions leaves the per-item descriptions out of it). Neither calls an endpoint, and nor do auth logout and auth status without --verify.

Every response uses the shared { status, code, message, data } envelope. See Errors for the error shapes and Limits & Quotas for every enforced number.