> For the complete documentation index, see [llms.txt](https://docs.mediafier.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediafier.ai/connect/cli-reference.md).

# CLI

The mediafier command set, global flags, and exit codes.

> **Every Mediafier capability as a composable command.** Install once, sign in, and script against the platform from a terminal, a shell pipeline, or a CI job — on the same identity, organization, and billing rails as every other access path.

***

## Install

```bash
npm install -g @mediafier/cli
```

Verify the install and your environment at any time:

```bash
mediafier doctor
```

***

## Authenticate

Sign in through your browser; the CLI stores and refreshes the session:

```bash
mediafier auth login
```

For headless and CI use, exchange an Agent Credential for an access token — see [Authentication & Agent Credentials](/connect/authentication.md):

```bash
export MEDIAFIER_TOKEN=<MEDIAFIER_TOKEN>
```

***

## Commands

### Connect & identity

| Command        | What it does                                              |
| -------------- | --------------------------------------------------------- |
| `auth login`   | Sign in through your browser.                             |
| `auth logout`  | Sign out and clear the local session.                     |
| `auth status`  | Show whether you're signed in and for which organization. |
| `auth keys`    | Create, list, rotate, and revoke Agent Credentials.       |
| `auth secrets` | Manage stored credentials your tools use.                 |

### Discover & call

| Command        | What it does                                                                                                                |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `tools list`   | List the tools available to your organization. Each tool's fully-qualified id is in `_meta["ai.mediafier/qualified_name"]`. |
| `tools call`   | Call a tool by its fully-qualified `<server_slug>:<surface_name>` id, with arguments.                                       |
| `tools invoke` | Alias of `tools call` (the agent-facing name) — identical behavior.                                                         |
| `resources`    | List the governed resources visible to your organization.                                                                   |
| `mediaclaw`    | List, inspect, run, and cancel MediaClaws (autonomous workflows).                                                           |
| `jobs`         | Check a long-running job's status, or cancel it.                                                                            |

Tools are addressed by a **fully-qualified id** — `<server_slug>:<surface_name>` (e.g. `mediafier-creative-ingest-mcp:full_creative_ingest`) — which you discover from `tools list`. A bare tool name is rejected, because two installed servers can share the same tool name.

```bash
mediafier tools list                       # discover tools + their qualified ids
mediafier tools call mediafier-mcp:get_job_status --args '{"job_id":"<uuid>"}'
mediafier tools invoke mediafier-mcp:get_job_status --args '{"job_id":"<uuid>"}'
```

### Command vocabulary

`commands` prints the curated, agent-facing command vocabulary without a full `tools/list` round-trip. It is **discovery-only** — it never executes anything; execution always goes through the family nouns (`tools`, `mediaclaw`, `jobs`, …).

| Command                                                              | What it does                                                                              |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `commands list`                                                      | Print the curated headline command vocabulary (offline — no token, no network).           |
| `commands list --remote`                                             | List the live partner headline commands available to your organization (via the gateway). |
| `commands list --family <mcp\|mediaclaw\|agent_operations\|account>` | Show every verb in one resource family.                                                   |
| `commands list --all`                                                | Show every command verb across all families.                                              |

The offline scope flags are mutually exclusive with each other and with `--remote`: pass at most one of `--family <x>`, `--all`, or `--remote`.

```bash
mediafier commands list                    # curated headline subset (offline)
mediafier commands list --family mediaclaw # one family's full verb set
mediafier commands list --remote           # your org's live partner commands
```

### Content

| Command           | What it does                                               |
| ----------------- | ---------------------------------------------------------- |
| `ingest creative` | Upload a local file and ingest it into your media library. |

### Account, usage & activity

| Command    | What it does                                                       |
| ---------- | ------------------------------------------------------------------ |
| `usage`    | Organization spend reports — summaries and rankings (admin/owner). |
| `activity` | Stream your organization's tool-call activity feed.                |
| `account`  | Show organization context and members. *(Coming soon.)*            |

### Operational analytics

Reporting surfaces for teams running agents at scale: `batches`, `insights` (failure clusters), `ledger` (learning signals), `signals` (discovery signals), `rationales` (decision rationales), and `overview` (spend summary). `pipelines` is *coming soon*.

### Local utilities

| Command   | What it does                                            |
| --------- | ------------------------------------------------------- |
| `doctor`  | Run local diagnostics: PATH, auth, network, clock.      |
| `welcome` | Print a first-run cheatsheet of common commands.        |
| `verify`  | Run an end-to-end gateway round-trip check (read-only). |
| `upgrade` | Upgrade the CLI in place. *(Coming soon.)*              |

***

## Global flags

| Flag                  | What it does                                             |
| --------------------- | -------------------------------------------------------- |
| `--help`, `-h`        | Show help and exit.                                      |
| `--version`, `-V`     | Print the CLI version and exit.                          |
| `--token <value>`     | Use a specific bearer token (overrides the environment). |
| `--gateway-url <url>` | Talk to a specific gateway.                              |
| `--debug`             | Send diagnostic output to stderr.                        |
| `--self-test`         | Run offline diagnostics and exit.                        |

***

## Exit codes

The CLI returns stable exit codes so scripts and CI can branch on them:

| Code | Meaning                                                |
| ---- | ------------------------------------------------------ |
| `0`  | Success.                                               |
| `1`  | Generic failure (unexpected error).                    |
| `64` | Usage error (unknown command or missing argument).     |
| `77` | Refused for a safety reason (e.g. wrong organization). |
| `78` | Command exists but isn't available yet.                |

***

## Next steps

* [Getting Started](/connect/getting-started.md) — install, connect, first call.
* [Authentication & Agent Credentials](/connect/authentication.md) — sign-in and headless keys.