---
title: CLI commands and flags
description: Every invideo CLI command, its flags and an example, from the live help, plus the help topics on arguments, URLs, output and waiting.
---
The invideo CLI is one binary that drives invideo from a shell: it generates video, images, voice and music with `invideo gen`, edits timelines with `invideo edit`, and exports. Install it, sign in, and check who you are:

```bash
curl -fsSL https://agents.invideo.io | sh
invideo auth login
invideo auth status
```

Every command has the same shape: `invideo <command> <subcommand> [<url>] [flags]`. The URL names what the command acts on, and every answer gives the URLs to use next. Run `invideo <command> <subcommand> --help` for one command's flags, and `invideo help <topic>` for a help topic.

## Rules for every command

These rules hold on every command. Your agent keeps them and gets clean, repeatable runs.

- **The URL is the handle.** Pass the URL of what you act on: a workspace, a project, a page, a sequence or an edit. Give the URLs you make to the person. Each one opens what it names in invideo.
- **Ask for JSON.** Add `--json` to get the whole answer as one JSON object, `next` included. Set `INVIDEO_JSON=1` to do this on every command.
- **Follow jobs with `--wait`.** A command that starts a generation, an export or an upload returns a URL at once. Run `invideo status <url> --wait` to follow it until it is over. `status` does not download.
- **Save files with `notebook show`.** Run `invideo notebook show <url> --out <dir>` on a sequence or an export card to save its file.
- **Name yourself in a project.** Run `invideo agent register` once, then pass `--as <name>` on every command in that project, or set `INVIDEO_AS`. Every project command takes `--as`, so the tables below leave it out.
- **Price before you pay.** Run a paid command with `--dry-run` first, then run it with `--max-credits`.

These flags work on every command:

| Flag | What it does |
| --- | --- |
| `--help` | Help for any command. |
| `--json` | The answer as one JSON object on stdout, with `next`. |
| `--tsv` | An answer's list as tab-separated rows under a header line. |
| `--out <dir>` | Saves files into the folder on the commands that save them: `invideo notebook show` (a sequence or an export card), and `invideo edit capture` and `invideo media video.frames` (frames). `invideo status` saves nothing, even with `--out`. |
| `--wait` | Waits for a generation, an export or an upload to finish. |
| `--timeout <s>` | Stops waiting after this many seconds. |

The commands come in the order `invideo --help` lists them.

## auth

The `auth` commands: sign in and out.

### auth login

Sign in, in the browser.

It takes no flags of its own.

```bash
invideo auth login
```

### auth logout

Forget this machine's sign-in.

It takes no flags of its own.

```bash
invideo auth logout
```

### auth status

Who you are signed in as.

It takes no flags of its own.

```bash
invideo auth status
```

## workspace

The `workspace` commands: your workspaces.

### workspace list

Your workspaces.

It takes no flags of its own.

```bash
invideo workspace list
```

## project

The `project` commands: list, create, show and rename projects.

### project list

Your projects, newest first.

| Flag | Value | What it does |
| --- | --- | --- |
| `--offset` | integer | Where the page starts: the next_offset of the page before. |
| `--query` | string | Only projects whose title contains this. |

```bash
invideo project list [<workspace-url>] --query teaser
```

### project new

Start a project.

| Flag | Value | What it does |
| --- | --- | --- |
| `--title` | string | Required. The project's name, as the person will see it, like "Product teaser". |

```bash
invideo project new [<workspace-url>] --title "Product teaser"
```

### project show

A project: its notebook, context, briefs and newest files.

It takes no flags of its own.

```bash
invideo project show https://invideo.io/@acme/launch-reel
```

### project rename

Rename what a URL names.

| Flag | Value | What it does |
| --- | --- | --- |
| `--name` | string | Required. The new name, like "Take 3 · slower, warmer". |

```bash
invideo project rename <url> --name "Launch"
```

## notebook

The `notebook` commands: pages, threads and sequences.

### notebook show

A page, a thread or a sequence.

It takes no flags of its own.

```bash
invideo notebook show <page-url>
invideo notebook show <card-url> --out ./out
```

On a sequence or an export card, `--out <dir>` saves the file into the folder. An exported video saves as `export.mp4`, whatever `--file-name` the export had; rename it after. `<card-url>` is `.sequences[0]` in the answer of `invideo edit export --json`.

### notebook new-page

A new notebook page.

| Flag | Value | What it does |
| --- | --- | --- |
| `--title` | string | Required. The page's title, as the person will see it. |

```bash
invideo notebook new-page <project-url> --title "Ideas"
```

### notebook mark

Approve or reject a sequence.

| Flag | Value | What it does |
| --- | --- | --- |
| `--status` | string | Required. accepted approves it, rejected rejects it. One of `accepted`, `rejected`. |
| `--reason` | string | Why, in a sentence the person sees beside the mark. |

```bash
invideo notebook mark <sequence-url> --status accepted --reason "best take"
```

## context

The `context` commands: the project's entries and briefs.

### context show

A context entry or a brief.

It takes no flags of its own.

```bash
invideo context show <project-url>/context
```

### context write

Replace a context entry or a brief.

| Flag | Value | What it does |
| --- | --- | --- |
| `--markdown` | string | Required. All of it, as `invideo context show` shows it (`--markdown @entry.md`). |
| `--description` | string | A context entry's line in the context's index; kept when left out. |
| `--revision` | integer | The revision your latest read gave. |

```bash
invideo context write <entry-url> --markdown @acme.md
```

### context edit

Change part of a context entry or a brief.

| Flag | Value | What it does |
| --- | --- | --- |
| `--new` | string | Required. What takes its place. |
| `--old` | string | Required. The exact text to change, as `invideo context show` shows it. |
| `--all` |  | Changes every place it is. |

```bash
invideo context edit <brief-url> --old "loud" --new "plain"
```

### context new-brief

Start a brief.

| Flag | Value | What it does |
| --- | --- | --- |
| `--description` | string | Required. What it is for, in a sentence or two. |
| `--name` | string | Required. Its name, like "Launch teaser". |

```bash
invideo context new-brief <project-url> --name "Launch" \
  --description "The launch teaser"
```

## edit

The `edit` commands: read, change, capture and export an edit.

### edit new

A new edit in a project.

| Flag | Value | What it does |
| --- | --- | --- |
| `--fps` | integer | Frames per second (default 30). |
| `--height` | integer | Height in pixels (default 1080). |
| `--name` | string | The edit's name, from what it is for, like "Product teaser" (default "Timeline"). |
| `--width` | integer | Width in pixels (default 1920). |

```bash
invideo edit new <project-url> --name "Teaser v1"
```

### edit change

Change an edit: a list of operations, all or none.

| Flag | Value | What it does |
| --- | --- | --- |
| `--operations` | list | Required. Operations, each an op and its fields, as a JSON list (`--operations @ops.json`). The file holds a bare list, `[ {...} ]`, with no `operations` wrapper. |
| `--timeline` | string | Required. Which timeline to change, from `invideo edit show`. |
| `--token` | string | Required. The state token from your latest read or change of this edit. |
| `--dry-run` |  | Checks the operations without applying them. |

```bash
invideo edit change <edit-url> --timeline T1 --token … --operations @ops.json
```

`<edit-url>` comes from `invideo edit new`. The `--token` value is the `state_token` from `invideo edit show`, and each change returns a fresh one.

### edit catalog

The operations, effects and transitions an edit takes.

| Flag | Value | What it does |
| --- | --- | --- |
| `--audio-effects` | list | Audio effect names whose settings to give. |
| `--effects` | list | Effect names whose parameters to give. |
| `--guides` | list | Guide names whose text to give, like custom_shader. |
| `--ops` | list | Op names whose fields to give. |
| `--transitions` | list | Transition names whose parameters to give. |

```bash
invideo edit catalog <edit-url> --ops trim_clip,add_text
```

### edit export

Render an edit to a file.

| Flag | Value | What it does |
| --- | --- | --- |
| `--format` | string | Required. video renders a file; premiere, final_cut and davinci make a project file that Premiere Pro, Final Cut Pro or DaVinci Resolve opens; invideo makes an invideo project. One of `video`, `premiere`, `final_cut`, `davinci`, `invideo`. |
| `--audio-format` | string | For video: the sound's format. One of `aac`, `opus`, `wav`. |
| `--encode-quality` | string | For video: how hard the encoder works; best is slowest. One of `draft`, `good`, `best`. |
| `--end` | number | For video: where it ends, in seconds. |
| `--file-name` | string | For video: the file's name. |
| `--fps` | number | For video: frames per second; the edit's own when left out. |
| `--idempotency-key` | string | Any text unique to this export, like a UUID. |
| `--media-packaging` | string | For premiere, final_cut and davinci: how the media comes with the project. One of `folder`, `zip`, `none`. |
| `--mode` | string | For video: a video, its sound alone, or one still image. One of `video`, `audio`, `image`. |
| `--quality` | string | For video: its height in pixels. One of `240`, `480`, `720`, `1080`. |
| `--start` | number | For video: where it starts, in seconds (default 0). |
| `--still-at` | number | With --mode image: the time of the still, in seconds. |
| `--target-lufs` | number | For video: the loudness to normalize the sound to, in LUFS. |
| `--timeline` | string | Which timeline in the edit to export, from `invideo edit show`. |

```bash
invideo edit export <edit-url> --format video --quality 1080 --json
invideo status <card-url> --wait
invideo notebook show <card-url> --out ./out
```

The export returns an export card. `<card-url>` is `.sequences[0]` in the JSON answer. `invideo status --wait` follows the card until it is over and saves nothing. `invideo notebook show` with `--out` saves the video as `export.mp4`; `--file-name` does not name the saved file. For `premiere`, `final_cut` and `davinci`, `completed` can arrive before the media package is ready: run `invideo notebook show` again until the files list is there.

### edit leave

Leave an edit (your cursor goes).

It takes no flags of its own.

```bash
invideo edit leave <edit-url>
```

### edit show

An edit's tracks and clips, and its state token.

| Flag | Value | What it does |
| --- | --- | --- |
| `--collection` | string | With --mode collection, the kind of object to list: timeline, track, clip, transition, gap, audio_track, audio_clip, audio_gap, asset, folder, font, lut, audio_bus, audio_effect, audio_send, marker, keyframe_lane, keyframe, motion_path_handle, guide, effect, shape_path, shape_paint, caption_slide, caption_sticker, color_mask, values. One of `timeline`, `track`, `clip`, `transition`, `gap`, `audio_track`, `audio_clip`, `audio_gap`, `asset`, `folder`, `font`, `lut`, `audio_bus`, `audio_effect`, `audio_send`, `marker`, `keyframe_lane`, `keyframe`, `motion_path_handle`, `guide`, `effect`, `shape_path`, `shape_paint`, `caption_slide`, `caption_sticker`, `color_mask`, `values`. |
| `--end-seconds` | number | With --mode window: where the window ends. |
| `--ids` | list | With --mode inspect: the ids to read. |
| `--limit` | integer | The most objects on one page. |
| `--mode` | string | overview lists the timelines; window reads tracks and the clips between --start-seconds and --end-seconds; collection lists one kind of object; inspect reads the objects named in --ids. One of `overview`, `inspect`, `window`, `collection`. |
| `--offset` | integer | Where the page starts: the next_offset of the page before. |
| `--parent-id` | string | With --mode collection: only objects that belong to this clip, track, timeline or keyframe lane. |
| `--property-path` | string | With --collection values: where the list sits in the object, like /vertices. |
| `--snapshot` | string | The snapshot the first page gave, for the pages after it. |
| `--start-seconds` | number | With --mode window: where the window starts (default 0). |
| `--timeline` | string | Which timeline in the edit, from `invideo edit show`. |

```bash
invideo edit show <edit-url>
```

### edit inspect

Objects of an edit by id, with every property you can change; a custom shader's source.

| Flag | Value | What it does |
| --- | --- | --- |
| `--ids` | list | Required. The objects' ids, from `invideo edit show`. |
| `--limit` | integer | The most objects on one page. |
| `--offset` | integer | Where the page starts: the next_offset of the page before. |
| `--snapshot` | string | The snapshot the first page gave, for the pages after it. |

```bash
invideo edit inspect <edit-url> --ids c5,c7
```

### edit check

Check an edit for problems.

It takes no flags of its own.

```bash
invideo edit check <edit-url>
```

### edit capture

Render frames of an edit as it looks now.

| Flag | Value | What it does |
| --- | --- | --- |
| `--at` | list | Required. Times in the edit, in seconds, up to 12. |
| `--timeline` | string | Which timeline in the edit, from `invideo edit show`. |

```bash
invideo edit capture <edit-url> --at 1,3.5 --out ./frames
```

`--out <dir>` saves the frames into the folder.

### edit point

Point at a time or clips, for people watching.

| Flag | Value | What it does |
| --- | --- | --- |
| `--text` | string | Required. What to say beside your cursor, in about four words. |
| `--at` | number | One time in the edit, in seconds. |
| `--ids` | list | Up to 10 clip ids from `invideo edit show`. |
| `--timeline` | string | Which timeline in the edit, from `invideo edit show`. |

```bash
invideo edit point <edit-url> --at 4 --text "this cut"
```

## branch

The `branch` commands: an edit's checkpoints and branches.

### branch list

Branches and checkpoints, each branch with its URL.

| Flag | Value | What it does |
| --- | --- | --- |
| `--limit` | integer | The most checkpoints on one page. |
| `--offset` | integer | Where the page of checkpoints starts. |
| `--snapshot` | string | The snapshot the first page gave. |

```bash
invideo branch list <edit-url>
```

### branch checkpoint

Save a checkpoint on a branch; returns the edits it saved.

| Flag | Value | What it does |
| --- | --- | --- |
| `--title` | string | Required. A short title for the checkpoint. |
| `--token` | string | Required. The state token from your latest read or change of this edit. |
| `--message` | string | A longer note on what changed. |

```bash
invideo branch checkpoint <edit-url> --title "rough cut" --token …
```

### branch restore

Restore a branch to a checkpoint; returns the edits it changed and the backup.

| Flag | Value | What it does |
| --- | --- | --- |
| `--checkpoint` | string | Required. A checkpoint, as `invideo branch list` names it. |
| `--token` | string | Required. The state token from your latest read or change of this edit. |

```bash
invideo branch restore <edit-url> --checkpoint … --token …
```

### branch new

Branch off now, or off a checkpoint with --checkpoint.

| Flag | Value | What it does |
| --- | --- | --- |
| `--name` | string | Required. The new branch's name. |
| `--token` | string | Required. The state token from your latest read or change of this edit. |
| `--checkpoint` | string | A checkpoint, as `invideo branch list` names it. |

```bash
invideo branch new <edit-url> --name tighter-intro --token …
```

The answer gives `branch_url`. Run every later `edit change`, `edit check`, `edit capture` and `edit export` on that `<branch-url>`, with a fresh token from `invideo edit show <branch-url>`. The main timeline's token is stale on the branch.

### branch edit-from-here

Open a checkpoint for editing on a branch of its own.

| Flag | Value | What it does |
| --- | --- | --- |
| `--checkpoint` | string | Required. A checkpoint, as `invideo branch list` names it. |
| `--token` | string | Required. The state token from your latest read or change of this edit. |

```bash
invideo branch edit-from-here <edit-url> --checkpoint … --token …
```

### branch tag

Tag a checkpoint.

| Flag | Value | What it does |
| --- | --- | --- |
| `--checkpoint` | string | Required. A checkpoint, as `invideo branch list` names it. |
| `--name` | string | Required. The tag's name. |
| `--token` | string | Required. The state token from your latest read or change of this edit. |

```bash
invideo branch tag <edit-url> --checkpoint … --name v1 --token …
```

### branch rename

Rename a branch.

| Flag | Value | What it does |
| --- | --- | --- |
| `--name` | string | Required. The branch's new name. |
| `--token` | string | Required. The state token from your latest read or change of this edit. |

```bash
invideo branch rename <branch-url> --name final --token …
```

### branch archive

Close a branch to edits; it keeps its history.

| Flag | Value | What it does |
| --- | --- | --- |
| `--token` | string | Required. The state token from your latest read or change of this edit. |

```bash
invideo branch archive <branch-url> --token …
```

### branch unarchive

Open an archived branch again.

It takes no flags of its own.

```bash
invideo branch unarchive <branch-url>
```

### branch default

Make a branch the default.

| Flag | Value | What it does |
| --- | --- | --- |
| `--token` | string | Required. The state token from your latest read or change of this edit. |

```bash
invideo branch default <branch-url> --token …
```

### branch final

Declare a branch final.

| Flag | Value | What it does |
| --- | --- | --- |
| `--token` | string | Required. The state token from your latest read or change of this edit. |

```bash
invideo branch final <branch-url> --token …
```

## asset

The `asset` commands: the project's files: upload and add.

### asset upload

Upload local files into a project.

| Flag | Value | What it does |
| --- | --- | --- |
| `--timeline` | string | With an edit's URL: which timeline's media bin, from `invideo edit show`. |

```bash
invideo asset upload <project-url> ./shots/*.mp4
```

### asset add

Bring in media from a link or the stock library.

| Flag | Value | What it does |
| --- | --- | --- |
| `--file-name` | string | The file's name with its extension, to name it by. |
| `--media-url` | string | A public http(s) link to the file; a file's URL from the project's …/assets; or a sequence's or font's URL (with an edit's URL). |
| `--mime-type` | string | The file's media type, like video/mp4. |
| `--stock` | string | A stock result's id from `invideo library search`, with the project's URL. |
| `--timeline` | string | With an edit's URL: which timeline's media bin, from `invideo edit show`. |

```bash
invideo asset add <project-url> --media-url https://…/clip.mp4
```

### asset show

A project's files, a folder or a file.

It takes no flags of its own.

```bash
invideo asset show <project-url>/assets
```

## media

Each `media` subcommand works on one file: a sequence URL, a file under the project's `…/assets`, or, for reads, a bin asset with `--asset`. Reads are free and return at once. `audio.transcript` and the model ops cost credits, so run them with `--dry-run` first. The tool ops, such as `video.trim` and `image.crop`, make a new file without a model. The dry run shows its price before anything starts.

`--asset` works on the reads only: `metadata`, `video.frames`, `audio.waveform`, `audio.loudness`, `audio.content`, `audio.onsets`, `audio.markers`, `audio.key`, `audio.sections` and `audio.beats`. Every op that costs credits or makes a file refuses `--asset` with `not_found`. Pass the file's sequence URL (`…/notebook/seq-N.M`) instead. `invideo asset upload` and `invideo asset add` return that URL.

In the examples, `<price>` is the `estimated_credits` from the same command run with `--dry-run`.

The examples below come from each command's help. Where a table marks a flag as required, add it to the example before you run it.

Most `media` subcommands also take some of these shared flags. Each subcommand below names the ones it takes.

| Flag | What it does |
| --- | --- |
| `--asset` | A file in the edit's media bin, by its id from `invideo edit show`. Reads only. |
| `--stock` | A stock result's id from `invideo library search`, with the project's URL. |
| `--dry-run` | Prices it; nothing starts. |
| `--idempotency-key` | Any text unique to this one, like a UUID. |
| `--max-credits` | The most it may cost, in the person's credits: nothing starts when it is higher. |

### media metadata

What a file is: streams, duration, size.

Shared flags: `--asset`, `--stock`.

```bash
invideo media metadata <sequence-url>
```

### media video.frames

Frames of a file at times in it.

| Flag | Value | What it does |
| --- | --- | --- |
| `--at` | list | Required. Times in the file, in seconds, up to 12. |

Shared flags: `--asset`, `--stock`.

```bash
invideo media video.frames <sequence-url> --at 0,2,4 --out ./frames
```

### media audio.waveform

A file's audio levels.

| Flag | Value | What it does |
| --- | --- | --- |
| `--limit` | integer | The most points, 16 a second (default 256). |
| `--offset` | integer | The first point, counted in points (16 a second) from the start. |

Shared flags: `--asset`, `--stock`.

```bash
invideo media audio.waveform <sequence-url>
```

### media audio.loudness

A file's loudness: integrated, true peak, range.

Shared flags: `--asset`, `--stock`.

```bash
invideo media audio.loudness <sequence-url>
```

### media audio.content

Where a file's sound is speech, music, effects or silence.

| Flag | Value | What it does |
| --- | --- | --- |
| `--limit` | integer | The most spans (default 256). |
| `--offset` | integer | The first span, counted from the start. |

Shared flags: `--asset`, `--stock`.

```bash
invideo media audio.content <sequence-url>
```

### media audio.onsets

Where each hit or transient in a file starts and peaks.

| Flag | Value | What it does |
| --- | --- | --- |
| `--limit` | integer | The most onsets (default 256). |
| `--offset` | integer | The first onset, counted from the start. |

Shared flags: `--asset`, `--stock`.

```bash
invideo media audio.onsets <sequence-url>
```

### media audio.markers

A file's tempo and musical markers.

| Flag | Value | What it does |
| --- | --- | --- |
| `--limit` | integer | The most markers (default 256). |
| `--offset` | integer | The first marker, counted from the start. |

Shared flags: `--asset`, `--stock`.

```bash
invideo media audio.markers <sequence-url>
```

### media audio.key

A file's musical key.

Shared flags: `--asset`, `--stock`.

```bash
invideo media audio.key <sequence-url>
```

### media audio.sections

A file's musical structure, coarse to fine.

Shared flags: `--asset`, `--stock`.

```bash
invideo media audio.sections <sequence-url>
```

### media audio.beats

Where a file's strong and weak beats fall.

| Flag | Value | What it does |
| --- | --- | --- |
| `--end-seconds` | number | Only beats by this time in the file, in seconds. |
| `--limit` | integer | The most beats (default 256). |
| `--offset` | integer | The first beat, counted from the start of the file or of the window --start-seconds and --end-seconds make. |
| `--start-seconds` | number | Only beats at or after this time in the file, in seconds. |

Shared flags: `--asset`, `--stock`.

```bash
invideo media audio.beats <sequence-url>
```

### media audio.transcript

Every word said in a file, with its time and speaker.

| Flag | Value | What it does |
| --- | --- | --- |
| `--end-seconds` | number | Only words that end by this time in the file, in seconds. |
| `--limit` | integer | The most words (default 256). |
| `--max-credits` | number | The most starting it may cost, in the person's credits: nothing starts when it is higher. |
| `--offset` | integer | The first word, counted from the start of the file or of the window --start-seconds and --end-seconds make. |
| `--start-seconds` | number | Only words that start at or after this time in the file, in seconds. |

Shared flags: `--asset`, `--dry-run`, `--stock`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media audio.transcript <sequence-url> --max-credits <price>
```

### media document.pages

An image sequence of each page of a PDF or deck.

| Flag | Value | What it does |
| --- | --- | --- |
| `--to` | string | A page's or thread's URL to put the pages on. |

```bash
invideo media document.pages <file-url>
```

`<file-url>` is the URL that `invideo asset upload` returns for the PDF or deck.

### media audio.separate

Split a file's sound into its stems.

| Flag | Value | What it does |
| --- | --- | --- |
| `--inputs` | object | The model's own extras, as `invideo gen model` lists them: -i key=value, or --input inputs.json. |
| `--model` | string | Which model runs it, one of: audio_separation. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media audio.separate <sequence-url> --max-credits <price>
```

### media audio.clean

Clean the voice in a file.

| Flag | Value | What it does |
| --- | --- | --- |
| `--inputs` | object | The model's own extras, as `invideo gen model` lists them: -i key=value, or --input inputs.json. |
| `--model` | string | Which model runs it, one of: clean_voice.clean_audio, clean_voice.clean_video. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media audio.clean <sequence-url> --max-credits <price>
```

### media video.upscale

Upscale a video.

| Flag | Value | What it does |
| --- | --- | --- |
| `--inputs` | object | The model's own extras, as `invideo gen model` lists them: -i key=value, or --input inputs.json. |
| `--model` | string | Which model runs it, one of: topaz_proteus_natural, pixverse_upscale, topaz_video_upscale, seedvr_video_upscale, flashvsr_video_upscale, bytedance_video_upscale, byteplus_vod_upscale, flux_3_video_upscale, topaz_astra_2, topaz_starlight_precise_26, topaz_gaia_2_animation. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.upscale <sequence-url> --max-credits <price>
```

### media image.upscale

Upscale an image.

| Flag | Value | What it does |
| --- | --- | --- |
| `--inputs` | object | The model's own extras, as `invideo gen model` lists them: -i key=value, or --input inputs.json. |
| `--model` | string | Which model runs it, one of: clarity_upscaler, crystal_upscaler, topaz_bloom_2, magnific_upscaler_creative, magnific_upscaler_precision_v2, pruna_p_image_upscale, byteplus_ultra_hd. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media image.upscale <sequence-url> --max-credits <price>
```

### media video.removeBackground

Remove a video's background.

| Flag | Value | What it does |
| --- | --- | --- |
| `--inputs` | object | The model's own extras, as `invideo gen model` lists them: -i key=value, or --input inputs.json. |
| `--model` | string | Which model runs it, one of: bria_video_bg_remove, veed_video_bg_remove.veed_bg_standard, veed_video_bg_remove.veed_bg_fast, pixelcut_video_bg_remove, ben_v2_video_bg_remove. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.removeBackground <sequence-url> --max-credits <price>
```

### media image.removeBackground

Remove an image's background.

| Flag | Value | What it does |
| --- | --- | --- |
| `--inputs` | object | The model's own extras, as `invideo gen model` lists them: -i key=value, or --input inputs.json. |
| `--model` | string | Which model runs it, one of: bria_bg_remove, birefnet_bg_remove. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media image.removeBackground <sequence-url> --max-credits <price>
```

### media video.trim

Trim a video to a time range.

| Flag | Value | What it does |
| --- | --- | --- |
| `--end-time` | number | Required. End Time (s). |
| `--start-time` | number | Required. Start Time (s). |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.trim <sequence-url>
```

### media video.reverse

Play a video backwards.

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.reverse <sequence-url>
```

### media video.changeSpeed

Speed up or slow down a video, or ramp its speed.

| Flag | Value | What it does |
| --- | --- | --- |
| `--start-speed` | number | Required. Start Speed. |
| `--end-speed` | number | End Speed. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.changeSpeed <sequence-url>
```

### media video.stitch

Join videos of the same aspect ratio into one.

| Flag | Value | What it does |
| --- | --- | --- |
| `--video-array` | list | Required. Videos. |
| `--aspect-ratio` | string | Aspect Ratio. |

Shared flags: `--dry-run`, `--idempotency-key`, `--max-credits`.

```bash
invideo media video.stitch <sequence-url>
```

### media video.sceneSplit

Split a video into its scenes.

| Flag | Value | What it does |
| --- | --- | --- |
| `--threshold` | number | Threshold. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.sceneSplit <sequence-url>
```

### media video.loop

Loop a video to a target length.

| Flag | Value | What it does |
| --- | --- | --- |
| `--target-duration` | number | Required. Target Duration (s). |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.loop <sequence-url>
```

### media video.extractFrameFirst

A video's first frame, as an image.

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.extractFrameFirst <sequence-url>
```

### media video.extractFrameLast

A video's last frame, as an image.

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.extractFrameLast <sequence-url>
```

### media video.extractFrameByNumber

One frame of a video by its number, as an image.

| Flag | Value | What it does |
| --- | --- | --- |
| `--frame-number` | number | Required. Frame Number. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.extractFrameByNumber <sequence-url>
```

### media video.extractFrameAtTime

The frame of a video at a time, as an image.

| Flag | Value | What it does |
| --- | --- | --- |
| `--time-seconds` | number | Required. Time (seconds). |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.extractFrameAtTime <sequence-url>
```

### media video.extractFrameInterval

Every Nth frame of a video, as images.

| Flag | Value | What it does |
| --- | --- | --- |
| `--frame-interval` | number | Required. Frame Interval. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.extractFrameInterval <sequence-url>
```

### media video.extractMsInterval

A frame of a video every N milliseconds, as images.

| Flag | Value | What it does |
| --- | --- | --- |
| `--interval-ms` | number | Required. Interval (ms). |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.extractMsInterval <sequence-url>
```

### media video.replaceAudio

Replace a video's sound with an audio file.

| Flag | Value | What it does |
| --- | --- | --- |
| `--audio-input` | string | Required. Audio Input. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.replaceAudio <sequence-url>
```

### media video.addAudioTrack

Mix an audio file into a video's sound.

| Flag | Value | What it does |
| --- | --- | --- |
| `--audio-input` | string | Required. Audio Input. |
| `--volume` | number | Volume. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.addAudioTrack <sequence-url>
```

### media video.resize

A video as MP4 at a target height.

| Flag | Value | What it does |
| --- | --- | --- |
| `--resolution` | string | Required. Resolution (height). |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.resize <sequence-url>
```

### media audio.toVideo

An audio file as a video with a blank picture.

| Flag | Value | What it does |
| --- | --- | --- |
| `--aspect-ratio` | string | Aspect Ratio. |
| `--fps` | number | FPS. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media audio.toVideo <sequence-url>
```

### media video.contactSheet

One image of frames across a video, in a grid.

| Flag | Value | What it does |
| --- | --- | --- |
| `--columns` | integer | Required. Columns. |
| `--resolution` | string | Required. Resolution (height). |
| `--rows` | integer | Required. Rows. |
| `--style` | string | Required. Style. |
| `--start-offset-ms` | integer | Start offset (ms). |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media video.contactSheet <sequence-url>
```

### media audio.trim

Trim an audio file to a time range.

| Flag | Value | What it does |
| --- | --- | --- |
| `--end-time` | number | Required. End Time (s). |
| `--start-time` | number | Required. Start Time (s). |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media audio.trim <sequence-url>
```

### media audio.extract

A video's sound, as an audio file.

| Flag | Value | What it does |
| --- | --- | --- |
| `--format` | string | Format. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media audio.extract <sequence-url>
```

### media audio.concat

Join audio files into one.

| Flag | Value | What it does |
| --- | --- | --- |
| `--audio-array` | list | Required. Audio Files. |
| `--gap-duration` | number | Gap Duration (s). |

Shared flags: `--dry-run`, `--idempotency-key`, `--max-credits`.

```bash
invideo media audio.concat <sequence-url>
```

### media audio.addAudioTrack

Mix an audio file over another.

| Flag | Value | What it does |
| --- | --- | --- |
| `--overlay-audio-input` | string | Required. Overlay Audio. |
| `--start-time` | number | Start Time (s). |
| `--volume` | number | Volume. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media audio.addAudioTrack <sequence-url>
```

### media image.collage

Combine images into one collage.

| Flag | Value | What it does |
| --- | --- | --- |
| `--image-array` | list | Required. Images. |
| `--aspect-ratio` | string | Aspect Ratio. |

Shared flags: `--dry-run`, `--idempotency-key`, `--max-credits`.

```bash
invideo media image.collage <sequence-url>
```

### media image.crop

Crop an image.

| Flag | Value | What it does |
| --- | --- | --- |
| `--h` | number | Required. Height. |
| `--w` | number | Required. Width. |
| `--x` | number | Required. X Position. |
| `--y` | number | Required. Y Position. |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media image.crop <sequence-url>
```

### media image.resizeAspectRatio

Resize an image to an aspect ratio.

| Flag | Value | What it does |
| --- | --- | --- |
| `--aspect-ratio` | string | Aspect Ratio. |
| `--max-height` | number | Max Height (px). |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media image.resizeAspectRatio <sequence-url>
```

### media image.resizeFit

Resize an image to fit a width and height.

| Flag | Value | What it does |
| --- | --- | --- |
| `--max-height` | number | Required. Max Height (px). |
| `--max-width` | number | Required. Max Width (px). |

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media image.resizeFit <sequence-url>
```

### media image.rotate

Rotate an image.

Shared flags: `--asset`, `--dry-run`, `--idempotency-key`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media image.rotate <sequence-url>
```

### media describe

What a video holds, from invideo's media understanding: a summary, chapters and captions. It spends credits, so price it with `--dry-run` first.

| Flag | Value | What it does |
| --- | --- | --- |
| `--start-seconds` | number | Only captions that start at or after this time in the file, in seconds. |
| `--end-seconds` | number | Only captions that end by this time in the file, in seconds. |
| `--limit` | integer | The most captions (default 256). |
| `--offset` | integer | The first caption, counted from the start of the file or of the window the two time flags make. |

Shared flags: `--asset`, `--dry-run`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media describe <sequence-url> --max-credits <price>
```

### media ask

A question about a stretch of a video, answered by invideo's media understanding. The stretch is at most a minute long. It spends credits, so price it with `--dry-run` first.

| Flag | Value | What it does |
| --- | --- | --- |
| `--question` | string | Required. What to answer about the stretch. |
| `--start-seconds` | number | Required. Where the stretch starts in the file, in seconds. |
| `--end-seconds` | number | Required. Where the stretch ends, at most 60 seconds after the start. |

Shared flags: `--asset`, `--dry-run`, `--max-credits`. Here `--asset` is refused: pass the file's sequence URL.

```bash
invideo media ask <sequence-url> --start-seconds 120 --end-seconds 150 \
  --question "When is the goal scored?" --max-credits <price>
```

## gen

The `gen` commands: generate with a model.

### gen models

Models you can generate with.

| Flag | Value | What it does |
| --- | --- | --- |
| `--output` | string | Only models that make this. One of `video`, `image`, `audio`, `three_d`. |
| `--query` | string | What to generate or a model's name, like "lip sync" or "seedance". |

```bash
invideo gen models <project-url> --query "video"
```

### gen model

One model and its inputs.

| Flag | Value | What it does |
| --- | --- | --- |
| `--model` | string | Required. A model id from `invideo gen models`, as `invideo gen run` takes it. |

```bash
invideo gen model <project-url> --model seedance_2_5.r2v
```

### gen run

Generate with a model; its inputs go as -i key=value.

| Flag | Value | What it does |
| --- | --- | --- |
| `--model` | string | Required. A model id from `invideo gen models`. |
| `--dry-run` |  | Prices it and checks the inputs; nothing starts. |
| `--idempotency-key` | string | Any text unique to this generation, like a UUID. |
| `--inputs` | object | The model's inputs, as `invideo gen model` lists them: each as -i key=value (`-i prompt=@prompt.txt` reads a file), or all of them as JSON with --input inputs.json. |
| `--max-credits` | number | The most the estimate may be, in the person's credits: nothing starts when it is higher. |

```bash
invideo gen run <page-url> --model seedance_2_5.r2v --dry-run \
  -i prompt="slow push on the bottle"
invideo gen run <page-url> --model seedance_2_5.r2v \
  --max-credits <price> --idempotency-key shot-1 \
  -i prompt="slow push on the bottle"
```

`<price>` is the `estimated_credits` in the dry run's answer. Pass the same inputs, the same way, on both runs. The paid run returns a thread URL; follow it with `invideo status <thread-url> --wait`, then save the result with `invideo notebook show <sequence-url> --out <dir>`. `<page-url>` comes from `invideo notebook new-page`.

Models retire. If a model is not found, your agent runs `find_models` with the job in words, uses the best match, and tells you.

## export

The `export` commands: export pages.

### export add

Add sequences to an export page.

| Flag | Value | What it does |
| --- | --- | --- |
| `--urls` | list | Required. Sequence and edit URLs of the project. |
| `--kind` | string | A new page's layout (default playlist). One of `playlist`, `canvas`, `doc`. |
| `--page` | string | An export page's URL, to add to it; leave it out for a new page. |
| `--title` | string | A new page's title. |

```bash
invideo export add <project-url> --urls <seq-url>,<seq-url>
```

### export edit

Reorder, retitle or trim an export page.

| Flag | Value | What it does |
| --- | --- | --- |
| `--order` | list | A playlist page's object ids in the order to show them. |
| `--remove` | list | Object ids to take off the page. |
| `--title` | string | The page's new title. |

```bash
invideo export edit <export-url> --title "Final cuts"
```

### export share

Share an export page.

| Flag | Value | What it does |
| --- | --- | --- |
| `--permissions` | object | For each visibility, whether people may comment and download, all three together, as one JSON object with `public`, `shared` and `private` keys, each holding `comment` and `download` booleans. |
| `--team-access` | string | What the workspace may do with the page. One of `view`, `comment`, `edit`. |
| `--visibility` | string | public: anyone with its URL; shared: the workspace; private: only you. One of `public`, `shared`, `private`. |

```bash
invideo export share <export-url> --visibility public
```

## agent

The `agent` commands: agents in a project and their messages.

### agent list

Every agent in a project.

It takes no flags of its own.

```bash
invideo agent list <project-url>
```

### agent register

Take a name in a project; pass it as `--as <name>` after.

| Flag | Value | What it does |
| --- | --- | --- |
| `--name` | string | Required. Your name: up to 24 lowercase letters, digits, - and _, like scout. |
| `--model` | string | The model you run on, if you know it, like opus. |

```bash
invideo agent register <project-url> --name scout
```

### agent message

Message an agent; its answer comes to your inbox.

| Flag | Value | What it does |
| --- | --- | --- |
| `--text` | string | Required. The message, in plain words. |

```bash
invideo agent message <agent-url> --text "trim the intro?" --as scout
```

### agent inbox

Your unread messages.

| Flag | Value | What it does |
| --- | --- | --- |
| `--before` | integer | A message id from an earlier inbox: the messages before it. |

```bash
invideo agent inbox <project-url> --as scout
```

## library

The `library` commands: search stock video, images, music and voices.

### library search

Search a stock library.

| Flag | Value | What it does |
| --- | --- | --- |
| `--library` | string | Required. `<model>_voices`, stock_video, stock_image or stock_music. |
| `--cursor` | string | Voices only: the cursor the last answer gave, for its next page. |
| `--query` | string | What to find, like "aerial city at night". |

```bash
invideo library search <project-url> --library stock_video \
  --query "city at night"
```

## status

Where generations, exports and uploads stand; --wait follows them until over.

It takes several URLs at once, from any of your projects. It has no flags of its own: add `--wait` to follow the jobs until they are over.

```bash
invideo status <sequence-url> <thread-url> --wait
```

## feedback

The `feedback` commands: report a bug or ask for a feature.

### feedback bug

Tell invideo something broke.

| Flag | Value | What it does |
| --- | --- | --- |
| `--summary` | string | Required. One line: what went wrong. |
| `--what-happened` | string | Required. The command you ran, its arguments, and the full answer. |
| `--expected` | string | What you expected instead. |
| `--kind` | string | broken, confusing or wrong_result. One of `broken`, `confusing`, `wrong_result`. |
| `--tool` | string | The command it happened with. |

```bash
invideo feedback bug <project-url> --summary "…" --what-happened "…"
```

### feedback feature

Ask invideo for something.

| Flag | Value | What it does |
| --- | --- | --- |
| `--summary` | string | Required. One line: what is needed. |
| `--details` | string | What you were trying to make, and why this was needed. |
| `--workaround` | string | What you did instead, if anything. |

```bash
invideo feedback feature <project-url> --summary "…"
```

## update

Update invideo to its latest release.

It updates an install from the script. With Homebrew, it says what to run instead (`brew upgrade invideo`). It takes no flags.

```bash
invideo update
```

## Help topics

The CLI has five help topics. `invideo help exit-codes` has its own page, [Exit codes](/reference/exit-codes). The other four follow, in plain words.

### arguments

A command's arguments are flags. Write a flag as `--name value` or `--name=value`.

- A true-or-false flag, like `--dry-run`, takes no value. `--dry-run=false` turns it off.
- A list repeats its flag (`--at 1 --at 3.5`), or takes commas (`--at 1,3.5`), or takes JSON.
- An object, like `--permissions`, takes JSON.
- `@path` reads a value from a file, like `--operations @ops.json`. A `-` reads it from stdin.
- `--input payload.json` gives the whole payload as one JSON object. Flags you add go on top of it. On `invideo gen run`, the file holds the bare inputs that `invideo gen model` lists, with no `inputs` wrapper.

A model's own inputs go with `-i`, one each, so they never clash with the command's flags. Run `invideo gen model --model <id>` to list a model's inputs.

```bash
invideo gen run <page-url> --model seedance_2_5.r2v \
  -i prompt="slow push" -i duration=5
```

### urls

A URL is the handle. Every command takes the URL of what it acts on, and every answer gives the URLs to use next.

A project's URL names its notebook. Under it sit the notebook pages (`…/notebook/<page>`), threads and sequences, the edits, the context and its entries (`…/context`), the files (`…/assets`), and the agents (`…/agents`). Give the person the URLs you make. Each one opens what it names.

### output

An answer is indented `key: value` text. What to do next comes after it. The text is the same on a terminal and in a pipe, so an agent reads it as a person does.

- `--json` prints the whole answer as one JSON object, `next` included, for `jq`. `INVIDEO_JSON=1` does this on every command.
- `--tsv` prints an answer's list as tab-separated rows under a header line. Its other fields and what to do next go to stderr, so `grep`, `cut` and `awk` read the rows.
- Errors and notices always go to stderr.

```bash
invideo branch list <edit-url> --tsv | cut -f2
```

### waiting

A command that starts something (a generation, an export or an upload) returns the URL to follow at once. Run `invideo status <url> --wait` to check back until the job is over. It follows jobs in any of your projects. `--timeout <s>` stops the wait after that many seconds.

With `--wait`, any command also tries again when nothing ran (exit code 7). A retry is the same request, so it never starts anything twice.

```bash
invideo status <sequence-url> <thread-url> --wait
```

## Related

- [Exit codes](/reference/exit-codes)
- [Environment variables](/reference/environment)
- [MCP tools](/reference/mcp-tools)
- [Timeline edit operations](/reference/edit-operations)
- [Models](/reference/models)