# CLI: make ads from your terminal

Make video and image ads from your terminal or your AI agent. Sign in with one click, make videos from a link, download them, and read JSON back.

The 10xvid CLI makes the same videos and image ads as the app, by typed command. It is made for two kinds of user: you in a terminal, and your AI agent (Claude Code, Cursor, Codex or any other that runs commands), which can make ads for you without opening the site.

## Install

You need Node.js 18 or newer.

```bash
npm install -g https://10xvid.com/cli/10xvid.tgz
```

Or run it once without installing:

```bash
npx -y https://10xvid.com/cli/10xvid.tgz login
```

## Sign in

```bash
10xvid login
```

A browser opens on 10xvid. Check that it shows the same code as your terminal, and press **Connect**; the code works for 10 minutes. The terminal gets an API key of its own, named "CLI on" and your computer's name (`--name` gives it another). It can make and read your videos, image ads and formats, and never touches your ads autopilot. It is listed on the [API keys](/app/api-keys) page, where you can delete it at any time. Your email address must be confirmed first. The key is kept in `config.json` in `~/.config/10xvid` (on Windows `%APPDATA%\10xvid`), readable only by you.

On a server or in CI, use a key from the API keys page instead:

```bash
export TENX_API_KEY=tenx_your_key_here
```

or `10xvid login --key tenx_your_key_here` (or the key on standard input with `--stdin`). A key given with `--key` or in `TENX_API_KEY` is used before the one `login` kept.

## Make your first video

```bash
10xvid make https://your-app.com --wait --download
```

The site is read (a few minutes), the video is made (about 5 to 15 minutes with Motion V1 Flash), and the file lands in the folder you are in, named after the video and its shape. Without `--wait`, the command answers at once with the ids, and `10xvid wait <id>` waits for them later.

More examples:

```bash
# vertical and square, 15 seconds, with what the ad should say
10xvid make https://your-app.com --aspect 9:16,1:1 --length 15 --notes "Lead with the free trial"

# three more from a format you made before (no new reading)
10xvid make --format your-app-com-abc123 --count 3

# an 8-bit pixel art film from an idea, no link needed
10xvid make "why your phone gets hot" --skill pixel --wait --download

# copy a competitor's winning ad for your product
10xvid make https://your-app.com --clone "https://www.facebook.com/ads/library/?id=1234567890"

# your own footage cut into an ad
10xvid make https://your-app.com --footage "https://drive.google.com/drive/folders/..."

# square image ads
10xvid image https://your-app.com --count 3 --wait --download

# a new version of a finished video
10xvid version MW9WOB32F7DBB0 --notes "Make the end card say Rated 4.9" --wait
```

## Commands

| Command | What it does |
|---|---|
| `login` | Connects this computer: a browser opens, you press Connect. `--key` or `--stdin` takes a key instead, `--name` names the key it makes, `--no-browser` only prints the link. An agent runs it in two steps: `--start` answers at once with the link and the code, `--finish` waits for Connect. |
| `make <link or words>` | Makes videos from a link, a format (`--format`), or an idea in words. |
| `image <link>` | Makes image ads (1:1 by default) from a link or a format (`--format`), with `--count`, `--aspect` and `--style`. |
| `status <id>` | A video's, an image ad's or a format's status, and its links once done. |
| `wait <id...>` | Waits until each is done, then prints the links. A format's id waits for its own videos. `--interval S` sets the seconds between checks (15 by default, at least 5). |
| `download <id...>` | Saves finished files as `<id>-9x16.mp4` (an image ad as `.png`) and so on, into `--out` (default: here); `--aspect` saves one shape only. A format's id saves its finished videos. |
| `version <id> --notes "..."` | A new version of a finished video, changed only as the notes say. Takes `--aspect` and `--remake` too. |
| `videos`, `images`, `formats` | What you made, newest first (`--limit`, `--before`; `videos` and `images` also `--format`). |
| `format <id>`, `format delete <id> --yes` | One format with its videos; delete it with all made from it. |
| `continue <format>` | Starts the step that waited for funds, once they are added. |
| `upload <format> <file...>` | Adds your screenshots, logo, videos, sound files or documents to a format (`--logo` marks the first as the logo). Name them by `@tag` in `--notes`. |
| `styles` | The styles, by id, for `--style`. `--family` shows one family. |
| `account` (or `whoami`) | Who you are signed in as, credits, balance and prices. |
| `setup <agent>` | Connects an AI agent to 10xvid: `claude`, `cursor`, `vscode`, `windsurf`, `opencode`, `codex` or `mcp`. See below. |
| `agents` | Prints the guide for AI agents. |
| `logout` | Forgets the key on this computer. |

`10xvid <command> --help` shows every option of a command. Every command also takes `--json`, `--quiet` (no messages for a person) and `--key KEY`.

### Options of make

| Option | What it is |
|---|---|
| `--format ID` | More videos from a format you made before, with no reading. |
| `--count N`, `--each "..."` | How many (1 to 6), or one video for each `--each`, all different. |
| `--aspect 9:16,1:1` | The shapes: `9:16`, `1:1`, `16:9` (or vertical, square, landscape). Default 9:16. |
| `--length S` | Seconds, 5 to 30 (an 8-bit film 15 to 60; with `--footage`, the most it may run, 6 to 60). |
| `--engine flash` or `motion` | [Motion V1 Flash](/docs/models), the default, or Motion V1 (half an hour or more, a fuller film). With `--style` or `--styles`, Motion V1 unless `--engine` says otherwise. |
| `--style ID`, `--styles a,b` | A style from `10xvid styles`; one video in each. |
| `--voiceover`, `--no-voiceover`, `--no-music` | The sound. |
| `--skill anime`, `pixel` (or `8-bit`) or `ugc` | An anime story, an 8-bit pixel art film, or a UGC ad (on the Studio plan and up). |
| `--clone LINK` | A winning ad to copy: Meta Ad Library, Facebook, Instagram, TikTok, YouTube, X or Vimeo. |
| `--footage LINK` | Your own videos to cut the ad from: a Google Drive link, a post, or an uploaded `@tag`. Repeat it. |
| `--file PATH` | A file of yours for these videos: a screenshot, logo, video, sound file or document. Repeat it; `--logo` marks the first as the logo. |
| `--notes "..."` | What the ads should say, show or avoid, in your words. |
| `--name`, `--about` | A product with no link yet: its name and what it does. |
| `--must-say`, `--must-avoid`, `--angle`, `--audience`, `--goal` | The rest of a brief, kept on the format `make` creates. With `--format`, the format keeps its own brief: these are left out, and the CLI says so. |
| `--blueprint` | Write the plan of the ad first (Motion V1). |
| `--wait`, `--download`, `--out DIR`, `--timeout MIN` | Wait for the videos, save them, where, and for how long (default 120 minutes). |

## For AI agents

One prompt sets up your agent. Paste it into Claude Code, Cursor, Codex or any AI coding tool:

```
Fetch and execute the appropriate instructions to set me up for 10xvid from https://10xvid.com/agent-setup/prompt.md
```

It installs the CLI, signs it in (you press **Connect** in your browser), and adds the 10xvid MCP server, with a skill for Claude Code. It is on the home of [the app](/app/agent) too, as **Onboard your agent to 10xvid**.

With the CLI signed in, one command connects an agent:

```bash
10xvid setup claude
```

For Claude Code it adds the [10xvid MCP server](/docs/api/mcp) with this computer's key, for every project, and a skill that teaches Claude the CLI (`--no-mcp` writes the skill alone). Then say `make 3 vertical ads for https://your-app.com`. The same for `cursor`, `vscode`, `windsurf` and `opencode` (the MCP server in their settings, and for OpenCode a short guide in its `AGENTS.md`); `10xvid setup mcp` prints the address and header for any other client. Codex and other agents that run commands use the CLI itself: `10xvid setup codex` adds a short guide to `~/.codex/AGENTS.md`, and `10xvid agents` prints the whole guide.

Every command takes `--json`: its answer is one JSON document on standard output, the API's own objects. Links to open, progress and messages for a person go to standard error. An error with `--json` is `{"error": "...", "code": "...", "exit": 4}`.

| Exit code | Meaning |
|---|---|
| `0` | Done. |
| `1` | An error: the message says what. |
| `2` | A wrong command or option. |
| `3` | Not signed in, or the key may not do this. |
| `4` | Not enough credits or balance: add funds on [Subscription](/app/subscription). |
| `5` | Still being made when `--timeout` ran out: run `10xvid wait` again. |
| `6` | A video failed. What it cost was given back. |

## What it costs

The same as the API: your plan's credits pay first, then the top up balance, a video by the second in each shape. `10xvid account` shows today's prices. See [API pricing](/docs/api/pricing).
