# Command Reference


The CLI command reference, grouped the same way the
[API reference](/api/v2) 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.

| Flag | Input |
| --- | --- |
| `--json` | print the raw [envelope](/concepts/envelope) instead of a table |
| `--quiet` | print ids alone, one per line |
| `--base-url` | the console to talk to, by default `https://console.intuizi.com` |
| `--idempotency-key` | reuse a key on a create, to retry one whose outcome is unknown |
| `--debug` | print every HTTP request and response on stderr |

`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](/cli/reference/auth#login)). No environment variable
sets the base URL.

The creates listed on [Idempotency](/concepts/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:

| Variable | Input |
| --- | --- |
| `INTUIZI_API_TOKEN` | a token to use instead of the stored one, for CI. It goes to whichever console the base URL names |
| `INTUIZI_NO_KEYRING` | set to `1` (any non-empty value other than `0` or `false`) to keep the token in the config file rather than the OS credential store (see [Token storage](/cli/reference/auth#token-storage)) |

## 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](/cli/reference/audiences#create).

**`--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](/concepts/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](/cli/reference/audiences#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](/cli/reference/audiences#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](/concepts/status-codes#3-cohort-status-scale-1-5). 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](/cli/reference/poi)). See
[The Async Model](/concepts/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](/cli/reference/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](/cli/reference/auth) - log in and out.
- [audiences](/cli/reference/audiences) - build audiences and Lookalike
  Models, and estimate an audience's size.
- [activations](/cli/reference/activations) - deliver an audience to an
  endpoint connection, and preview a frequency filter.
- [cohorts](/cli/reference/cohorts) - import your own identifiers from a file,
  an upload, or an audience.
- [schedules](/cli/reference/schedules) - rebuild an audience on a recurring
  window.
- [projects](/cli/reference/projects) - the folders everything is filed under.
- [poi](/cli/reference/poi) - manage your own POI data.
- [uploads](/cli/reference/uploads) - send a file to Intuizi.
- [reference](/cli/reference/catalogs) - read the catalogs of ids every other
  command needs.
- [usage](/cli/reference/usage) - data scanned in a month, and the monthly
  limit.
- [webhooks](/cli/reference/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](/concepts/envelope). See [Errors](/concepts/errors) for the error
shapes and [Limits & Quotas](/concepts/limits) for every enforced number.

{{< cards >}}
  {{< card link="/developers/cli/quickstart/" title="Quickstart" subtitle="Look up ids, build an audience, deliver it." >}}
  {{< card link="/developers/cli/reference/auth/" title="Auth" subtitle="Log in and out." >}}
{{< /cards >}}