> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adside.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Using commands

> How commands, flags, output and errors work.

Commands read as an area, a resource and an action:

```bash theme={null}
adside assets list
adside meta campaigns list
adside reporting creatives rank
```

`adside --help` lists every area, and `adside assets --help` lists the commands of one, with their flags. The [command reference](https://docs.adside.ai/cli/reference/account.md) has the same on one page per area.

To find the command for a task, describe the task in a few words. This runs on your machine, without logging in, and needs adside 0.4.0 or later:

```bash theme={null}
adside cli search "top creatives by spend"
```

## Give a command its input

Each input is a flag. Booleans take a value, and JSON flags take a quoted JSON value:

```bash theme={null}
adside assets list --search "summer sale"
adside research companies refresh-ads --company-id cmabc123 --force-refresh true
adside reporting performance query --from 2026-10-01 --to 2026-10-31 --metrics '["spend","ctr"]'
```

To pass everything at once, use `--json`, or read it from a file with `--input-file`:

```bash theme={null}
adside reporting performance query --json '{"from":"2026-10-01","to":"2026-10-31","level":"ad"}'
adside reporting performance query --input-file query.json
```

Set the workspace for one command with `--workspace-id`. See [Choose a workspace](https://docs.adside.ai/workspaces-and-permissions.md#choose-a-workspace).

## Read the output

Commands print JSON, ready for `jq`. Add `--output text` for a summary to read, on commands that have one.

```bash theme={null}
adside assets list | jq '.assets[].name'
```

A command that returns a file takes `--out <file>`.

## Get the next page

A list returns one page. Its output carries the value for the next one, like `nextCursor` on `adside assets list`. Pass that to the flag the command lists, such as `--cursor` or `--after`, until there is none.

## Errors

A command that fails prints the message on stderr and exits with `1`. The message starts with the HTTP status and the [error code](https://docs.adside.ai/api/errors.md):

```text theme={null}
HTTP 404: NOT_FOUND: Asset not found
```

Media jobs say more with their exit code, and always print the job on stdout:

| Exit code | Meaning |
| - | - |
| `0` | Completed |
| `1` | Bad input or an HTTP error |
| `2` | Failed, cancelled or expired |
| `3` | Still running when `--wait-timeout` ran out |

## Stable and beta commands

A stable command keeps working: renaming or removing it comes with a deprecation window. A beta command may still change, and the reference marks it.

## Let an agent run it

Log in yourself, then let your agent run `adside` in the same terminal. It acts as you. A command makes its change on the first call, with no [confirmation](https://docs.adside.ai/confirmations.md#the-cli-and-the-api) step, so ask your agent to check with you before one that deletes or sends something.

On ad platforms the CLI only reads for now, apart from posting to your workspace's Instagram account (`adside meta instagram-posts publish` and `delete`). To let an agent change campaigns, [connect it over MCP](https://docs.adside.ai/mcp/connect.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.