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

# Command reference

> Every ContentHero CLI command, its arguments and its options.

Every command the CLI exposes, grouped by resource. 123 commands.

Run `contenthero schema commands` to get this same information as JSON, which is the discovery path for agents.

## Global options

These apply to every command.

| Flag | Purpose |
| - | - |
| `-v, --version` | print the CLI version |
| `--json` | output raw JSON (the default) |
| `--human` | render human-readable output instead of JSON |
| `--api-key <key>` | API key (overrides env and the stored credential) |
| `--base-url <url>` | API base URL (overrides env and stored config) |

## `account`

### `contenthero account get`

Show your balance, spend this month, monthly spend cap, plan and auto top-up

### `contenthero account update`

Change an account setting; only the flags you pass change

| Option | Purpose |
| - | - |
| `--spend-cap <credits>` | monthly spend cap in credits, or "none" to remove it (owner only; needs billing:write) |

## `archive`

### `contenthero archive <assetType> <id>`

Archive an asset, or restore it with --off (reversible; requires favorites:write)

| Argument | Required | Purpose | | | | | |
| - | - | - | - | - | - | - | - |
| `assetType` | yes | card | brand\_kit | brand\_kit\_section | project | space | media |
| `id` | yes | the asset id, or the media id when assetType is media (a1B2c3D4-2 for one output of several) | | | | | |

| Option | Purpose |
| - | - |
| `--off` | restore instead of archiving |

## `audio`

### `contenthero audio enhance <source>`

Enhance an audio file (level loudness, clean up background noise). Asynchronous.

| Argument | Required | Purpose |
| - | - | - |
| `source` | yes | source audio (URL or output id) to enhance |

| Option | Purpose |
| - | - |
| `--duration <seconds>` | source audio length in seconds (required for --cost, and when the source is not a stored ContentHero asset) |
| `--cost` | estimate the credit cost instead of running |
| `--no-wait` | return the outputId immediately instead of waiting |
| `--timeout <seconds>` | how long to wait before handing back the outputId Defaults to `600`. |

### `contenthero audio enhance-clips <projectId>`

Enhance the audio OF EXISTING CLIPS on an editor timeline, in place. One job per SOURCE: a recording's clips are enhanced together so the level and noise floor stay consistent across cuts, while separate recordings stay separate jobs.

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the editor project whose clips to enhance |

| Option | Purpose |
| - | - |
| `--clips <ids...>` | clip ids to enhance (omit for every audible clip on the timeline) |
| `--no-wait` | return the outputIds immediately instead of waiting |
| `--timeout <seconds>` | how long to wait before handing back the outputIds Defaults to `600`. |

### `contenthero audio isolate <source>`

Isolate vocals from an audio file (remove background noise and music)

| Argument | Required | Purpose |
| - | - | - |
| `source` | yes | source audio (URL or output id) to isolate |

| Option | Purpose |
| - | - |
| `--duration <seconds>` | source audio length in seconds (required for --cost) |
| `--project <id>` | editor project to place the result on (omit for a standalone library output) |
| `--placement <json>` | placement intent as JSON, e.g. \{"mode":"atPlayhead"} (omit to place at the playhead when known, else append) |
| `--playhead <frame>` | current playhead frame, for playhead-relative placement |
| `--cost` | estimate the credit cost instead of running |
| `--no-wait` | return the outputId immediately instead of waiting |
| `--timeout <seconds>` | how long to wait before handing back the outputId Defaults to `600`. |

## `auth`

### `contenthero auth login`

Authenticate the CLI. Browser-assisted by default; --with-key stores an existing key.

| Option | Purpose |
| - | - |
| `--with-key [key]` | store an existing API key (pass the key, or pipe it via stdin). Omit to use the browser flow. |

### `contenthero auth logout`

Delete the stored credential (env / --api-key are unaffected)

### `contenthero auth status`

Verify the active API key and show the account it resolves to

## `avatar`

### `contenthero avatar create <name>`

Create an avatar and start generating its first look (spends credits)

| Argument | Required | Purpose |
| - | - | - |
| `name` | yes | avatar name, at least 3 characters |

| Option | Purpose |
| - | - |
| `--age <age>` | apparent age, e.g. '20s', '35' |
| `--gender <gender>` | gender presentation |
| `--ethnicity <ethnicity>` | ethnicity, for a more specific likeness |
| `--niche <niche>` | content niche; repeatable |
| `--style <style>` | visual style hint for the portrait |
| `-d, --description <text>` | description of the character |
| `--voice <voiceId>` | default voice id (see `contenthero voice list`) |
| `--ref <urlOrId>` | photo of a REAL PERSON to anchor identity to; repeatable. Only use photos of someone who agreed |
| `--cost` | show the credit cost and exit without creating |

### `contenthero avatar delete <id>`

Delete an avatar (its looks survive and can be filed onto another avatar)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the avatar id |

### `contenthero avatar get <id>`

Get one avatar with its looks

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the avatar id |

### `contenthero avatar list`

List avatars (base look + default voice)

| Option | Purpose |
| - | - |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |

### `contenthero avatar look add <avatarId>`

File images you already own onto an avatar as looks (costs nothing)

| Argument | Required | Purpose |
| - | - | - |
| `avatarId` | yes | the avatar id |

| Option | Purpose |
| - | - |
| `--image <urlOrId>` | image to file; repeatable |

### `contenthero avatar look remove <avatarId> <lookId>`

Remove a look (trashed, recoverable for 30 days)

| Argument | Required | Purpose |
| - | - | - |
| `avatarId` | yes | the avatar id |
| `lookId` | yes | the look id (see `contenthero avatar get`) |

### `contenthero avatar update <id>`

Rename an avatar, set its default look or voice, or move it among your avatars

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the avatar id |

| Option | Purpose |
| - | - |
| `--name <name>` | new name, at least 3 characters |
| `--default-look <lookId>` | look to make the default (also becomes the profile photo) |
| `--voice <voiceId>` | default voice id, or "none" to clear it |
| `--after <id>` | place it immediately after this item of the same list |
| `--before <id>` | place it immediately before this item of the same list |
| `--position <end>` | place it at an end of the list instead of beside an item |

## `brand-kit`

### `contenthero brand-kit create`

Create a brand kit: empty, imported from its websites and accounts, or as a copy (requires brand:write)

| Option | Purpose |
| - | - |
| `--name <text>` | the kit's name; optional when a website or social profile url is given |
| `--website-url <url>` | one of the brand's websites. Repeatable; the first is the primary site |
| `--extract` | import the kit from its websites and own --brand-account profiles (returns immediately) |
| `--duplicate-from <id>` | copy an existing brand kit instead of starting empty |
| `--sections <json>` | section content as JSON: \[\{ key, body }] to fill a starter section, \[\{ sectionName, tab, body? }] to add one |
| `--brand-account <ref>` | the owner's OWN profile: a tracked-account id, or a profile url / platform:handle to ADD one. Repeatable |
| `--inspiration-account <ref>` | a competitor/creator profile: same forms as --brand-account. Repeatable |
| `--logo <ref>` | a logo: a url, or a generation id to copy in (e.g. out9-2). Repeatable; the first is primary |
| `--display-logo <ref>` | the logo for compact places: one of the --logo refs; at most one per kit |
| `--asset <ref>` | a brand asset: a url, or a generation id to copy in. Repeatable |
| `--color <hex[:role[:name]]>` | a palette color, e.g. #1A2B3C:primary:Ocean, or #FFFFFF::Paper with no role. Role is primary, secondary, tertiary or accent, each held by one color. Repeatable |
| `--title-font <family>` | the font family for titles |
| `--body-font <family>` | the font family for body text |

### `contenthero brand-kit extract <id>`

Re-run a kit's import from its websites and own accounts (returns immediately)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the brand kit id |

### `contenthero brand-kit get <id>`

Get one brand kit: --detail summary lists every section without its body; a section filter returns just those sections with their bodies (add --history for earlier versions); neither returns the whole kit

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the brand kit id |

| Option | Purpose |
| - | - |
| `--detail <level>` | 'summary' (every section, no bodies) or 'full' (the default); not with a filter |
| `--keys <list>` | section keys, comma-separated |
| `--roles <list>` | section roles, comma-separated |
| `--tabs <list>` | 'overview', 'voice' and/or 'visual', comma-separated |
| `--history` | with a filter, also return each section's earlier versions |

### `contenthero brand-kit knowledge add <brandKitId>`

Add an item to a brand kit's knowledge base (requires brand:write)

| Argument | Required | Purpose |
| - | - | - |
| `brandKitId` | yes | the brand kit id |

| Option | Purpose |
| - | - |
| `--text <text>` | add a text note |
| `--url <url>` | scrape and add a web page |
| `--youtube <url>` | add a YouTube video transcript |
| `--file <path>` | add a local document or image file (PDF, DOCX, PNG, etc.) |
| `--file-url <url>` | add a hosted file by URL the server fetches (large files, video, audio) |
| `--file-ext <ext>` | extension for --file-url when not in the URL, e.g. pdf |
| `--title <title>` | optional title (else derived) |
| `--cost` | estimate the credit cost instead of adding (video and audio are measured, not processed) |

### `contenthero brand-kit knowledge get <brandKitId> <knowledgeId>`

Get one knowledge item with its stored body

| Argument | Required | Purpose |
| - | - | - |
| `brandKitId` | yes | the brand kit id |
| `knowledgeId` | yes | the knowledge item id |

### `contenthero brand-kit knowledge list <brandKitId>`

List the knowledge items in a brand kit (the complete index)

| Argument | Required | Purpose |
| - | - | - |
| `brandKitId` | yes | the brand kit id |

| Option | Purpose |
| - | - |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |

### `contenthero brand-kit knowledge remove <brandKitId> <knowledgeId>`

Remove a knowledge item and its embeddings (requires brand:write)

| Argument | Required | Purpose |
| - | - | - |
| `brandKitId` | yes | the brand kit id |
| `knowledgeId` | yes | the knowledge item id to remove |

### `contenthero brand-kit knowledge search <brandKitId> <query>`

Semantic search over a brand kit's knowledge base

| Argument | Required | Purpose |
| - | - | - |
| `brandKitId` | yes | the brand kit id |
| `query` | yes | what to search for (natural language) |

| Option | Purpose |
| - | - |
| `--limit <n>` | max matches (default 8) |
| `--threshold <n>` | minimum similarity 0-1 (default 0.45) |

### `contenthero brand-kit list`

List the account's brand kits (default first; excludes archived unless --archived)

| Option | Purpose |
| - | - |
| `--favorite` | only favorited brand kits |
| `--archived` | only archived brand kits (default excludes archived) |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |

### `contenthero brand-kit update <id>`

Update a brand kit: section content, colors and fonts, media and accounts, and its place among your kits (requires brand:write)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the brand kit id |

| Option | Purpose |
| - | - |
| `--name <text>` | |
| `--website-url <url>` | one of the brand's websites. Repeatable; the first is the primary site. Replaces the list |
| `--default` | make this the default brand kit, un-defaulting every other |
| `--sections <json>` | section writes as JSON, only the sections you change, all or nothing: \[\{ key, body, expectedVersion }] edits one (or revertTo, sectionName, width; afterId, beforeId or position moves it in its tab); \[\{ sectionName, tab, body? }] adds one |
| `--brand-account <ref>` | the owner's OWN profile: a tracked-account id, or a profile url / platform:handle to ADD one. Repeatable. REPLACES the list |
| `--inspiration-account <ref>` | a competitor/creator profile: same forms as --brand-account. Repeatable. REPLACES the list |
| `--logo <ref>` | a logo: a url, or a generation id to copy in (e.g. out9-2). Repeatable; the first is primary. REPLACES the list |
| `--display-logo <ref>` | the logo for compact places: one of the --logo refs; at most one per kit |
| `--asset <ref>` | a brand asset: a url, or a generation id to copy in. Repeatable. REPLACES the list |
| `--color <hex[:role[:name]]>` | a palette color, e.g. #1A2B3C:primary:Ocean, or #FFFFFF::Paper with no role. Role is primary, secondary, tertiary or accent, each held by one color. Repeatable. REPLACES the list; --color none clears it |
| `--title-font <family>` | the font family for titles; none clears it |
| `--body-font <family>` | the font family for body text; none clears it |
| `--after <id>` | place it immediately after this item of the same list |
| `--before <id>` | place it immediately before this item of the same list |
| `--position <end>` | place it at an end of the list instead of beside an item |

## `card`

### `contenthero card create <title>`

Create a post (requires planner:write)

| Argument | Required | Purpose |
| - | - | - |
| `title` | yes | post title |

| Option | Purpose |
| - | - |
| `--platform <platform>` | primary platform: youtube, instagram, tiktok, facebook, linkedin, x, threads, general |
| `--space <space>` | which space's board (from `contenthero space list`); default space if omitted |
| `--stage <stage>` | stage id, slug, or name (defaults to the first stage) |
| `--cover-url <url>` | public URL for the post cover |
| `--cover-output-id <id>` | media token (short id, output id or first 8 characters, optionally with "-N") for the cover |
| `--tags <list>` | comma-separated tag names (must exist; see `tag list`) |
| `--after <id>` | place it immediately after this item of the same list |
| `--before <id>` | place it immediately before this item of the same list |
| `--position <end>` | place it at an end of the list instead of beside an item |

### `contenthero card get <id>`

Get one card with its posts and assets

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the post id |

### `contenthero card list`

List one space's cards (newest-updated first; defaults to the default space)

| Option | Purpose |
| - | - |
| `--space <id>` | which space's board (from `contenthero space list`), or all for every space; default space if omitted |
| `--archived` | only ARCHIVED cards (excluded by default) |
| `--platform <platform>` | filter by platform |
| `--stage <stage>` | filter by stage (id, slug, or name) |
| `--tag <tag>` | only cards with this tag |
| `--search <text>` | case-insensitive title search |
| `--favorite` | only favorited posts |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |
| `--sort <field>` | the field to sort by |
| `--order <order>` | the sort direction |

### `contenthero card publish <id>`

Publish a card's posts NOW (requires publish:write; pushes to live socials)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the post id |

| Option | Purpose |
| - | - |
| `--platform <platform>` | publish only this platform (default: every post on the card) |

### `contenthero card update <id>`

Update a post's fields, including its stage and its place in its column (requires planner:write)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the post id |

| Option | Purpose |
| - | - |
| `--title <text>` | |
| `--platform <platform>` | |
| `--stage <stage>` | move the post to this stage (id, slug, or name) |
| `--space <space>` | move the card to another space (id or slug); without --stage it lands in that space's matching stage, or its first |
| `--also <id>` | another card id to apply this to; repeatable. Fields describing ONE card (title, notes, cover) still need exactly one |
| `--notes <text>` | working notes; REQUIRES --expected-revision, from `card get` |
| `--expected-revision <n>` | the revision `card get` reported. Required with --notes: a card's notes have several independent writers, and a write that cannot name the revision it read would silently erase the others |
| `--notes-edits <json>` | change the notes in place, as JSON, IN ORDER: \{"append":"..."} adds to the end; \{"find":"...","replace":"..."} swaps the one place find matches. All or none; no --expected-revision needed |
| `--cover-url <url>` | public URL for the post cover |
| `--cover-output-id <id>` | media token (short id, output id or first 8 characters, optionally with "-N") for the cover |
| `--tags <list>` | comma-separated tag names (replaces the set; must exist) |
| `--schedule <when>` | ISO-8601 publish time for the card AND its posts, or "clear" |
| `--posts <json>` | the card's posts as JSON. REPLACES the set, keyed by platform; \[] detaches all |
| `--assets <json>` | the card's assets as JSON, IN ORDER: \[\{"id":...}] keeps one; add one with exactly one of \{"outputId"} (media: generated, uploaded or imported), \{"assetUrl"} (a link), \{"contentId"} (an inspiration post) or \{"projectId"} (an editor or canvas project). REPLACES the list; \[] clears it |
| `--after <id>` | place it immediately after this item of the same list |
| `--before <id>` | place it immediately before this item of the same list |
| `--position <end>` | place it at an end of the list instead of beside an item |

## `config`

### `contenthero config list`

Show the resolved configuration (key source and base URL)

### `contenthero config path`

Print the config and credential file paths

### `contenthero config set <key> <value>`

Set a preference. Supported keys: base-url

| Argument | Required | Purpose |
| - | - | - |
| `key` | yes | the preference to set (base-url) |
| `value` | yes | the value |

## `connected-account`

### `contenthero connected-account get <id>`

Get one connected account's detail

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the connected account id |

### `contenthero connected-account list`

List connected accounts (default first)

| Option | Purpose |
| - | - |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |

## `content`

### `contenthero content analyze <id>`

Analyze a tracked post: Break It Down, or its scenes with --kind scenes. Free when the result exists, otherwise it spends credits (see --cost)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the content id (from content list, a tracked account, or a card inspiration asset) |

| Option | Purpose |
| - | - |
| `--kind <kind>` | breakdown (default) or scenes (the scene map and a frame of each scene, priced per minute of video) |
| `--cost` | show the credit cost instead of analyzing (nothing runs, nothing is charged) |
| `--no-wait` | return at once instead of waiting for a running analysis |
| `--timeout <sec>` | how long to wait for a running analysis (default 600) |

### `contenthero content get <id>`

Get one tracked post in full (engagement, hashtags, optional transcript and Break It Down analysis)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the content id (from content list, a tracked account, or a card inspiration asset) |

| Option | Purpose |
| - | - |
| `--transcript [grain]` | include the transcript: none, text, segments (default none) |
| `--start-ms <n>` | transcript window start, ms into the media |
| `--end-ms <n>` | transcript window end, ms into the media |
| `--transcript-search <text>` | only the transcript segments containing this phrase |
| `--analysis` | include the full Break It Down analysis (availability always reports) |
| `--analysis-sections <list>` | only these analysis sections, comma-separated (names come from the availability line) |
| `--scenes <grain>` | the post's scenes: map, or frames (the same map with each scene's frame url); --start-ms/--end-ms narrow them |

### `contenthero content list`

List tracked content, ranked by outlier score, or by relevance when you pass --search

| Option | Purpose |
| - | - |
| `--scope <scope>` | which accounts: all, inspiration, brand (default all) |
| `--platform <platform>` | filter to one platform (youtube, instagram) |
| `--type <type>` | content type, e.g. video, short, reel |
| `--min-score <n>` | only content at or above this outlier score |
| `--max-score <n>` | only content at or below this outlier score |
| `--min-views <n>` | minimum view count |
| `--max-views <n>` | maximum view count |
| `--min-duration <n>` | minimum duration in seconds |
| `--max-duration <n>` | maximum duration in seconds |
| `--min-followers <n>` | minimum follower count of the post's account |
| `--max-followers <n>` | maximum follower count of the post's account |
| `--since <window>` | published within: week, month, 3months, 6months, year, 2years |
| `--published-after <iso>` | published on or after this ISO timestamp (wins over --since) |
| `--published-before <iso>` | published on or before this ISO timestamp |
| `--search <text>` | finds posts by meaning and by keyword across title, creator, description and transcript, ranked by relevance; returns only the posts judged relevant, so no rows means nothing matched |
| `--account <id>` | limit to this tracked account; repeatable |
| `--added-by-you` | only the one-off posts saved by url |
| `--brand-kit <id>` | scope to the accounts linked to this brand kit |
| `--favorite` | only content the account has favorited |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |
| `--sort <field>` | the field to sort by |
| `--order <order>` | the sort direction |

## `context`

### `contenthero context`

Read what the user is currently viewing in the open app (requires context:read)

| Option | Purpose |
| - | - |
| `--project <id>` | scope to a specific project (editor/canvas) |
| `--capture` | also capture a fresh screenshot of the live viewport (the user's screen; slower) |
| `--render` | also render your work inline (images); ephemeral. Add --count with a range for several frames. Frames across a range are how you judge motion, timing and pacing: the closer together they are, the finer the motion they show. |
| `--frame <n>` | image: which single timeline frame (omit for the current playhead) |
| `--slide <id>` | image (canvas): which slide id (omit for the focused slide) |
| `--slide-index <n>` | image (canvas): 1-based slide index (alternative to --slide) |
| `--from-frame <n>` | start timeline frame of the range (several frames) |
| `--to-frame <n>` | end timeline frame of the range |
| `--count <n>` | how many frames across the range (omit for one at the focus point) |
| `--width <n>` | image: the width in pixels to render at, to check legibility at the size it will be seen (a thumbnail, a feed card). Height follows the aspect ratio. The size used is reported in rendered. |
| `--region <x,y,w,h>` | image: render only this rectangle, in composition units (get\_project's compositionSpace), to inspect detail at full resolution. Without --width, it renders at native scale; rendered reports pixelsPerCompositionUnit. |
| `--save <path>` | write the produced image(s) to this file (several frames append -1, -2, ...) |

## `element`

### `contenthero element create`

Create a Kling element from 2-4 images (or 1 video)

| Option | Purpose | | | |
| - | - | - | - | - |
| `--name <name>` | referenced in the prompt as @name | | | |
| `--description <text>` | what the Kling element represents | | | |
| `--category <category>` | auto | character | location | prop Defaults to `"auto"`. |
| `--image <urlOrId>` | image URL or output id; repeatable (2-4) | | | |
| `--video <urlOrId>` | a single video URL or output id (alternative to images) | | | |

### `contenthero element delete <id>`

Delete a Kling element

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | Kling element id |

### `contenthero element get <id>`

Get one Kling element by id

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | Kling element id |

### `contenthero element list`

List your saved Kling elements

| Option | Purpose |
| - | - |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |

### `contenthero element update <id>`

Update a Kling element's name, description, or category

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | Kling element id |

| Option | Purpose | | | |
| - | - | - | - | - |
| `--name <name>` | | | | |
| `--description <text>` | | | | |
| `--category <category>` | auto | character | location | prop |

## `favorite`

### `contenthero favorite <assetType> <id>`

Favorite an asset, or clear it with --off (requires favorites:write)

| Argument | Required | Purpose | | | | | | | | |
| - | - | - | - | - | - | - | - | - | - | - |
| `assetType` | yes | card | voice | brand\_kit | project | inspiration\_content | gallery | transition | space | media |
| `id` | yes | the asset id, or the media id when assetType is media (a1B2c3D4-2 for one output of several) | | | | | | | | |

| Option | Purpose |
| - | - |
| `--off` | clear the favorite instead of setting it |

## `folder`

### `contenthero folder create <name>`

Create a folder (manual by default; --smart for a saved query with --text)

| Argument | Required | Purpose |
| - | - | - |
| `name` | yes | folder name |

| Option | Purpose |
| - | - |
| `--smart` | create a smart (saved-query) folder |
| `--text <text>` | smart-folder semantic query text |
| `--parent <id>` | nest under this parent folder id |

### `contenthero folder delete <id>`

Delete a folder and its subtree (pointers only; assets are never deleted)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | folder id |

### `contenthero folder get <id>`

A folder's contents (a folder id or a derived key: recents, favorites, edits, canvas, cards)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | folder id or derived key |

| Option | Purpose |
| - | - |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |
| `--small-copies` | give each image its small copy, where the library keeps one: for drawing images small, never for downloading, delivering or showing large |

### `contenthero folder list`

List your folders plus the built-in derived folders

| Option | Purpose |
| - | - |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |

### `contenthero folder update <id>`

Rename, move, re-query a folder, and file or unfile items (requires library:write)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the folder id |

| Option | Purpose |
| - | - |
| `--name <text>` | a new name |
| `--parent <id>` | move under this folder id, or "none" for the top level |
| `--text <text>` | a smart folder's new semantic query text (the same query `folder create --smart --text` sets) |
| `--also <id>` | apply to this folder too; repeatable. Name and query still need exactly one |
| `--add <ref>` | file an item: a media id (a1B2c3D4-2), project:\<id> or card:\<id>. Repeatable |
| `--remove <ref>` | unfile an item: a media id, project:\<id> or card:\<id>. Repeatable |
| `--move-item <ref>` | move an item within this manual folder, named as --add names one; with --move-after, --move-before or --move-position |
| `--move-after <ref>` | the item it lands immediately after |
| `--move-before <ref>` | the item it lands immediately before |
| `--move-position <end>` | an end of the folder instead of beside an item |

## `generate`

### `contenthero generate audio`

Generate audio with ElevenLabs: speech (TTS), music, or a sound effect

| Option | Purpose |
| - | - |
| `-m, --model <id>` | audio model id (see `contenthero model list --type audio`) |
| `--prompt <text>` | for music / sfx: what to generate |
| `--text <text>` | for TTS: the words to speak |
| `--voice <id>` | for TTS: the ElevenLabs voice id |
| `--voice-name <name>` | for TTS: human-readable voice name (display only) |
| `--duration <seconds>` | for music / sfx: length in seconds |
| `--prompt-influence <0-1>` | for sfx: how literally to follow the prompt |
| `--cost` | estimate the credit cost instead of generating |
| `--project <id>` | editor project to place the result on (omit for a standalone library output) |
| `--placement <json>` | placement intent as JSON, e.g. \{"mode":"atPlayhead"} (omit to place at the playhead when known, else append) |
| `--playhead <frame>` | current playhead frame, for playhead-relative placement |

### `contenthero generate board [prompt]`

Generate a Reference Board (dense multi-panel reference sheet, 3:4 / 4K)

| Argument | Required | Purpose |
| - | - | - |
| `prompt` | no | subject description (required when no --ref is given) |

| Option | Purpose |
| - | - |
| `-t, --type <type>` | board type (`contenthero model get reference-boards` lists them) |
| `--ref <urlOrId>` | source image (URL or output id); repeatable |
| `-n, --num <count>` | number of board variations (1-4) |
| `--name <name>` | optional board name |
| `--avatar <id>` | associate the board with this avatar (see `contenthero avatar list`) |
| `--cost` | estimate the credit cost instead of generating (nothing runs, nothing is charged) |
| `--no-wait` | return the outputId immediately instead of waiting for the render |
| `--timeout <seconds>` | how long to wait before handing back the outputId Defaults to `600`. |

### `contenthero generate image [prompt]`

Generate one or more images from a prompt (optionally image-to-image)

| Argument | Required | Purpose |
| - | - | - |
| `prompt` | no | the image prompt (optional for a few reference-only models) |

| Option | Purpose |
| - | - |
| `-m, --model <id>` | image model id (see `contenthero model list --type image`) |
| `--aspect <ratio>` | aspect ratio, e.g. 16:9, 1:1, 9:16 |
| `--resolution <res>` | resolution, e.g. 1K, 2K, 4K (model-dependent) |
| `-n, --num <count>` | number of variations (1-4) |
| `--ref <urlOrId>` | reference image (URL or output id); repeatable |
| `--avatar <id>` | file the result onto this avatar as a new look (see `contenthero avatar list`) |
| `--cost` | estimate the credit cost instead of generating (nothing runs, nothing is charged) |
| `--no-wait` | return the outputId immediately instead of waiting for the render |
| `--timeout <seconds>` | how long to wait before handing back the outputId Defaults to `600`. |
| `--project <id>` | editor project to place the result on (omit for a standalone library output) |
| `--placement <json>` | placement intent as JSON, e.g. \{"mode":"atPlayhead"} (omit to place at the playhead when known, else append) |
| `--playhead <frame>` | current playhead frame, for playhead-relative placement |

### `contenthero generate lip-sync`

Animate a portrait so the subject speaks (image + audio or script)

| Option | Purpose |
| - | - |
| `-m, --model <id>` | lip-sync model id (see `contenthero model list --type video`) |
| `--image <urlOrId>` | portrait to animate (image URL or output id) |
| `--audio <urlOrId>` | existing speech clip (audio URL or output id). Use this OR --script + --voice |
| `--script <text>` | text for the subject to speak (requires --voice) |
| `--voice <id>` | ElevenLabs voice id to speak the script |
| `--voice-name <name>` | human-readable voice name (display only) |
| `--motion <text>` | optional motion / expression hint |
| `--resolution <res>` | resolution, e.g. 480p, 720p, 1080p (model-dependent) |
| `--audio-duration <seconds>` | length of --audio in seconds (improves cost accuracy) |
| `--cost` | estimate the credit cost instead of generating (nothing runs, nothing is charged) |
| `--no-wait` | return the outputId immediately instead of waiting for the render |
| `--timeout <seconds>` | how long to wait before handing back the outputId Defaults to `600`. |

### `contenthero generate video [prompt]`

Generate a video from a prompt (optionally with frames / references)

| Argument | Required | Purpose |
| - | - | - |
| `prompt` | no | the video prompt |

| Option | Purpose |
| - | - |
| `-m, --model <id>` | video model id (see `contenthero model list --type video`) |
| `--aspect <ratio>` | aspect ratio, e.g. 16:9, 9:16 |
| `--resolution <res>` | resolution, e.g. 720p, 1080p, 4K (model-dependent) |
| `--duration <seconds>` | clip length in seconds (model-dependent) |
| `--keep-input-length` | keep the input video's full length (video edit only) |
| `--audio` | enable generated audio (models that support it) |
| `-n, --num <count>` | number of variations (1-4) |
| `--negative <text>` | what to avoid (models that support it) |
| `--start-frame <urlOrId>` | first frame (image URL or output id) |
| `--end-frame <urlOrId>` | last frame (image URL or output id) |
| `--ref <urlOrId>` | reference image (URL or output id); repeatable |
| `--ref-video <urlOrId>` | reference video (URL or output id); repeatable |
| `--ref-audio <urlOrId>` | reference audio (URL or output id); repeatable |
| `--kling-element <id>` | saved Kling element id (Kling 3.0, @name in prompt); repeatable |
| `--element <id>` | deprecated alias for --kling-element |
| `--multi-shot` | enable multi-shot mode (e.g. WAN 2.6) |
| `--shots <json>` | Kling 3.0 multi-shot: JSON array of \{ prompt, duration } objects |
| `--cost` | estimate the credit cost instead of generating (nothing runs, nothing is charged) |
| `--no-wait` | return the outputId immediately instead of waiting for the render |
| `--timeout <seconds>` | how long to wait before handing back the outputId Defaults to `600`. |
| `--project <id>` | editor project to place the result on (omit for a standalone library output) |
| `--placement <json>` | placement intent as JSON, e.g. \{"mode":"atPlayhead"} (omit to place at the playhead when known, else append) |
| `--playhead <frame>` | current playhead frame, for playhead-relative placement |

## `generation`

### `contenthero generation status <id>...`

Show one or more generations; blocks until they finish unless --no-wait

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | one or more outputIds from a generate / upscale command |

| Option | Purpose |
| - | - |
| `--no-wait` | take an instant snapshot instead of blocking |
| `--timeout <seconds>` | how long to block before handing back Defaults to `600`. |

## `kling-element`

### `contenthero kling-element create`

Create a Kling element from 2-4 images (or 1 video)

| Option | Purpose | | | |
| - | - | - | - | - |
| `--name <name>` | referenced in the prompt as @name | | | |
| `--description <text>` | what the Kling element represents | | | |
| `--category <category>` | auto | character | location | prop Defaults to `"auto"`. |
| `--image <urlOrId>` | image URL or output id; repeatable (2-4) | | | |
| `--video <urlOrId>` | a single video URL or output id (alternative to images) | | | |

### `contenthero kling-element delete <id>`

Delete a Kling element

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | Kling element id |

### `contenthero kling-element get <id>`

Get one Kling element by id

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | Kling element id |

### `contenthero kling-element list`

List your saved Kling elements

| Option | Purpose |
| - | - |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |

### `contenthero kling-element update <id>`

Update a Kling element's name, description, or category

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | Kling element id |

| Option | Purpose | | | |
| - | - | - | - | - |
| `--name <name>` | | | | |
| `--description <text>` | | | | |
| `--category <category>` | auto | character | location | prop |

## `login`

### `contenthero login`

Authenticate the CLI. Browser-assisted by default; --with-key stores an existing key.

| Option | Purpose |
| - | - |
| `--with-key [key]` | store an existing API key (pass the key, or pipe it via stdin). Omit to use the browser flow. |

## `logout`

### `contenthero logout`

Delete the stored credential (env / --api-key are unaffected)

## `media`

### `contenthero media get <id>`

Get one media item by id (studio output, or an upload/stock item with --source)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | media id (a1B2c3D4, or a1B2c3D4-2 for one output of several) |

| Option | Purpose |
| - | - |
| `--source <source>` | which library the id belongs to: creations, uploads, stock (default creations) |
| `--save <dir>` | download each output to \<dir> (materialize the bytes for local viewing or re-ingestion) |

### `contenthero media import <url>`

Import a remote URL as first-class media (requires library:write)

| Argument | Required | Purpose |
| - | - | - |
| `url` | yes | public https URL to fetch and re-host |

| Option | Purpose |
| - | - |
| `--content-type <mime>` | MIME type override (else taken from the response) |
| `--name <name>` | file name override (used for the extension) |
| `--no-wait` | return the outputId immediately instead of waiting for the import |
| `--timeout <seconds>` | how long to wait before handing back the outputId Defaults to `600`. |

### `contenthero media list`

List the library's files: every file, or one part of the library with --source

| Option | Purpose |
| - | - |
| `--source <source>` | which part of the library: all, creations, uploads, exports (default all) |
| `--type <types>` | filter by media type (comma-separated): image, video, audio, doc, other |
| `--kind <kind>` | creations only: filter by asset class: creation, board, look |
| `--favorite` | only favorited files |
| `--archived` | only archived files |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |
| `--sort <field>` | the field to sort by |
| `--order <order>` | the sort direction |
| `--small-copies` | give each image its small copy, where the library keeps one: for drawing images small, never for downloading, delivering or showing large |

### `contenthero media search <query>`

Semantically search your library (creations, uploads, stock, brand) by describing the content

| Argument | Required | Purpose |
| - | - | - |
| `query` | yes | natural-language description of the media to find |

| Option | Purpose |
| - | - |
| `--kinds <kinds>` | restrict to media kinds (comma-separated): image, video, audio |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |
| `--small-copies` | give each image its small copy, where the library keeps one: for drawing images small, never for downloading, delivering or showing large |

### `contenthero media share [mediaIds]...`

A public link to outputs of your finished generations: one gives its generation's link, opened at that output; several give a new link to them as a set (requires studio:write)

| Argument | Required | Purpose |
| - | - | - |
| `mediaIds` | no | one or more media ids, as these commands print them; with --off, one |

| Option | Purpose |
| - | - |
| `--title <title>` | a title for a set of two or more |
| `--off` | stop sharing: one media id, or the link with --link; a stopped link never opens again |
| `--link <shareUrl>` | with --off, the media link to stop |

### `contenthero media upload <file>`

Upload a local file as first-class media (requires library:write)

| Argument | Required | Purpose |
| - | - | - |
| `file` | yes | path to the local file |

| Option | Purpose |
| - | - |
| `--content-type <mime>` | MIME type override (else inferred from the extension) |
| `--name <name>` | file name override (else the basename) |

### `contenthero media watch <idOrUrl>`

Watch a VIDEO as low-res keyframes across a time window (inspect raw footage)

| Argument | Required | Purpose |
| - | - | - |
| `idOrUrl` | yes | a studio output id (short id, full id or first 8 characters) OR a media URL on our storage |

| Option | Purpose |
| - | - |
| `--from <sec>` | start of the source-time window (seconds) |
| `--to <sec>` | end of the source-time window (seconds) |
| `--frames <n>` | how many keyframes (default 8) |
| `--frame-width <px>` | each keyframe's width in pixels (default 640; 160 to 1280) |
| `--save <dir>` | write the keyframes to \<dir> |

### `contenthero media zoom <idOrUrl> <region>`

Cut a region from a media file's original and get it at its own detail (never enlarged)

| Argument | Required | Purpose |
| - | - | - |
| `idOrUrl` | yes | a media id (a1B2c3D4-2) OR a media URL on our storage |
| `region` | yes | x,y,width,height in the file's own pixels (clamped to the file) |

| Option | Purpose |
| - | - |
| `--save <file>` | write the cut to \<file> (webp) |

## `model`

### `contenthero model get <id>`

Get one model's full request shape (the parameters it accepts)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | model id (from `model list`) |

### `contenthero model list`

List the models available to this key (the discovery catalog)

| Option | Purpose |
| - | - |
| `--type <type>` | filter by content type: image, video, or audio |

## `project`

### `contenthero project apply <projectId>`

Apply a batch of ops to a project composition. Ops both CREATE (create\_clip, insert\_track, insert\_prebuilt\_track, add\_transition) and EDIT (move\_clip, trim\_clip, update\_clip, delete\_clip, remove\_background, disable\_ranges, update\_transition, remove\_transition, ...) and KEYFRAME ops (add\_keyframe, update\_keyframe, remove\_keyframe, apply\_combo). One-shot cleanups: remove\_silence, remove\_filler\_words, extract\_audio. Templates: insert\_template places one from `template list`, branded with the project's brand kit (see `schema timeline` for shapes). Build items from the `example` skeletons in `schema timeline` / `schema layer`; run `project get` first for the current revision and pass it as --expected-revision for safe concurrent edits. Requires editor:write.

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

| Option | Purpose |
| - | - |
| `--ops <json>` | the ops as a JSON array string |
| `--ops-file <path>` | read the ops JSON array from a file |
| `--intent <text>` | a short description of the edit (for attribution) |
| `--expected-revision <n>` | revision for optimistic concurrency (from `project get`) |

### `contenthero project create`

Create a project (requires editor:write)

| Option | Purpose | |
| - | - | - |
| `--type <type>` | editor | canvas (default: editor) |
| `--surface <type>` | deprecated alias for --type | |
| `--title <text>` | project title (default: Untitled) | |
| `--orientation <ratio>` | e.g. 16:9, 9:16, 1:1 (default: 16:9) | |
| `--width <n>` | pixel width (default: from orientation) | |
| `--height <n>` | pixel height (default: from orientation) | |
| `--fps <n>` | frames per second for an editor project: 24, 25, 30, 50 or 60 (default: 30) | |
| `--brand-kit <id>` | associate this brand kit with the project | |
| `--card <id>` | link the new project to this card in the same call (also needs planner:write) | |

### `contenthero project delete <projectId>`

PERMANENTLY delete a project, irreversible (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

| Option | Purpose |
| - | - |
| `--yes` | confirm the irreversible permanent delete |

### `contenthero project duplicate <projectId>`

Copy a project: the same type, size, composition and brand kit (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

### `contenthero project export <projectId>`

Export a project to a file: video, stills, documents, and for an editor project its sound, subtitles and transcript (`contenthero schema export` lists every format) (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

| Option | Purpose | | | | |
| - | - | - | - | - | - |
| `--format <format>` | a format `contenthero schema export` lists (default mp4) | | | | |
| `--resolution <res>` | output resolution for ANY format: 480p | 720p | 1080p | 2k | 4k. Defaults 720p for an editor mp4, the project native size for a still. 1080p+ is plan-gated |
| `--quality <q>` | mp4 quality: low | recommended | high | | |
| `--frame <n>` | editor still (png/jpg) only: timeline frame to render (default 0) | | | | |
| `--no-watermark` | remove the watermark (plan-gated) | | | | |
| `--max-chars-per-line <n>` | subtitles only: longest line, 20 to 80 characters (default 42) | | | | |
| `--max-lines-per-card <n>` | subtitles only: lines per card, 1 to 4 (default 2) | | | | |
| `--show-speakers` | subtitles only: name who speaks, when there is more than one speaker | | | | |
| `--timecodes` | transcripts only: start each paragraph with its timecode | | | | |
| `--wait` | poll until the export finishes and print the URL | | | | |
| `--timeout <ms>` | max wait when --wait (default 600000) | | | | |

### `contenthero project export-status <exportId>`

Poll an export job by id (requires editor:read)

| Argument | Required | Purpose |
| - | - | - |
| `exportId` | yes | the export id |

### `contenthero project exports <projectId>`

List a project's exports, newest first: finished ones with their download and share page, running ones with their status (requires editor:read)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

| Option | Purpose |
| - | - |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |

### `contenthero project get <projectId>`

Read a project's composition + revision (summary by default; requires editor:read)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

| Option | Purpose |
| - | - |
| `--detail <detail>` | 'summary' (default) or 'full' (the complete composition) |
| `--from <frame>` | timeline only: start frame of a window (clips overlapping \[from, to]) |
| `--to <frame>` | timeline only: end frame of the window |
| `--track <trackId>` | timeline only: scope to one track by id |
| `--slide <slideId>` | canvas only: scope to one slide by id (applies to --detail full too) |

### `contenthero project import`

Import a PPTX/Slides file URL or a Canva design into a new canvas project (requires editor:write)

| Option | Purpose | |
| - | - | - |
| `--source-type <type>` | pptx | canva |
| `--file-url <url>` | PPTX / slides file URL (when --source-type pptx) | |
| `--design-id <id>` | Canva design id (when --source-type canva) | |
| `--title <text>` | title for the created project | |
| `--card <id>` | link the new project to this card in the same call (also needs planner:write) | |

### `contenthero project list`

List projects, both editor + canvas (requires editor:read)

| Option | Purpose | |
| - | - | - |
| `--filter <state>` | archived | favorited (omitted = active) |
| `--type <type>` | editor | canvas (omitted = both) |
| `--surface <type>` | deprecated alias for --type | |
| `--search <text>` | case-insensitive title search | |
| `--limit <n>` | how many to return | |
| `--cursor <cursor>` | the previous page's cursor | |
| `--sort <field>` | the field to sort by | |
| `--order <order>` | the sort direction | |

### `contenthero project redo <projectId>`

Re-apply the edit most recently undone, the editor's own redo (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

| Option | Purpose |
| - | - |
| `--expected-revision <n>` | the revision you last saw; refused if the project has moved since |

### `contenthero project settings get <projectId>`

Read a video project's timeline settings (requires editor:read)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

### `contenthero project settings update <projectId>`

Change some timeline settings; a setting left out is left alone (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

| Option | Purpose |
| - | - |
| `--magnetic-track` | turn magnetic track on |
| `--no-magnetic-track` | turn magnetic track off |
| `--snapping` | turn snapping on |
| `--no-snapping` | turn snapping off |
| `--linkage` | turn linkage on |
| `--no-linkage` | turn linkage off |
| `--follow-playhead` | turn follow playhead on |
| `--no-follow-playhead` | turn follow playhead off |
| `--skimming` | turn skimming on |
| `--no-skimming` | turn skimming off |
| `--skip-disabled-clips` | turn skip disabled clips on |
| `--no-skip-disabled-clips` | turn skip disabled clips off |
| `--linked-tracks <json>` | which kinds of track a linked edit reaches, as JSON with media, audio and text booleans |

### `contenthero project share <projectId>`

Make the project's public live link, or revoke it with --off; anyone with the link sees the project as it is now (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

| Option | Purpose |
| - | - |
| `--off` | revoke the link; a revoked link stays dead |

### `contenthero project transcript <projectId>`

Read a project's transcript mapped to its timeline clips (requires editor:read)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the editor project id |

| Option | Purpose |
| - | - |
| `--search <text>` | only clip segments whose text contains this substring |
| `--start <ms>` | source-media start time in ms (with --end, filters to this window; word mode also clips words to it) |
| `--end <ms>` | source-media end time in ms |
| `--granularity <level>` | 'clip' (default) or 'word' (adds word timing + timeline frames + confidence + speaker, derived silences, audio events) |
| `--pace-threshold <ms>` | word mode: minimum pause (ms) to report as a silence ("Pace"); defaults to the project setting, else 500 |
| `--padding-start <ms>` | word mode: breathing room (ms) kept after speech at a silence start edge (negative tightens) |
| `--padding-end <ms>` | word mode: breathing room (ms) kept before speech at a silence end edge (negative tightens) |

### `contenthero project undo <projectId>`

Reverse the project's most recent edit, the editor's own undo (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

| Option | Purpose |
| - | - |
| `--expected-revision <n>` | the revision you last saw; refused if the project has moved since |
| `--revision <n>` | a specific revision to reverse (default: the most recent edit) |

### `contenthero project update <projectId>`

Change a project's own fields: rename, resize, brand kit, cover (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

| Option | Purpose |
| - | - |
| `--title <text>` | a new title |
| `--orientation <ratio>` | a new aspect ratio |
| `--width <n>` | a new pixel width |
| `--height <n>` | a new pixel height |
| `--brand-kit <id>` | the brand kit to associate, or none to clear it |
| `--cover <choice>` | the cover: auto (follows the composition), frame:\<n> (a chosen frame or slide index), or media:\<id> (a library image) |
| `--cover-position <x,y>` | where the cover is framed, as percentages of its width and height, or none for the default framing |

### `contenthero project version copy <projectId> <versionId>`

Make a new project from a version (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |
| `versionId` | yes | the version id (from `project version list`) |

### `contenthero project version delete <projectId> <versionId>`

Remove a version (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |
| `versionId` | yes | the version id (from `project version list`) |

### `contenthero project version list <projectId>`

List a project's saved versions, newest first (requires editor:read)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

| Option | Purpose |
| - | - |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |

### `contenthero project version rename <projectId> <versionId> <label>`

Name a version; an empty label clears its name (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |
| `versionId` | yes | the version id (from `project version list`) |
| `label` | yes | the new name |

### `contenthero project version restore <projectId> <versionId>`

Put a version back into its project; the current state is saved as a version first (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |
| `versionId` | yes | the version id (from `project version list`) |

### `contenthero project version save <projectId>`

Save the project's current state as a version (requires editor:write)

| Argument | Required | Purpose |
| - | - | - |
| `projectId` | yes | the project id |

| Option | Purpose |
| - | - |
| `--label <text>` | a name for the version |

## `schema`

### `contenthero schema <kind> [command]...`

Read a vocabulary another command accepts: commands, platform, timeline, layer, export, link, code or effect

| Argument | Required | Purpose |
| - | - | - |
| `kind` | yes | which vocabulary: commands, platform, timeline, layer, export, link, code, effect |
| `command` | no | kind commands only: a command path to scope the dump, e.g. "generate image" |

| Option | Purpose |
| - | - |
| `--platform <platform>` | kind platform only: the platform to read; omit to list every platform |
| `--format <format>` | kind platform with --platform only: narrow to one format (e.g. reel, short, story) |
| `--json-schema` | kinds timeline and layer only: also return each type's full JSON Schema (large) |
| `--name <name>` | kind effect only: the effect to read in full. Omit to list the effects. |

## `space`

### `contenthero space create <name>`

Create a space. --duplicate-from copies another space's STAGES, never its cards

| Argument | Required | Purpose |
| - | - | - |
| `name` | yes | space name |

| Option | Purpose |
| - | - |
| `--cover <url>` | cover image URL for the space tile |
| `--duplicate-from <id>` | copy this space's stages into the new one |

### `contenthero space delete <id>`

Delete an EMPTY space. The server refuses one that still holds cards, naming the count

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | space id |

### `contenthero space get <id>`

One space, with its live card count

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | space id |

### `contenthero space list`

List the account's spaces, most recently active first

| Option | Purpose |
| - | - |
| `--archived` | only archived spaces (excluded by default) |
| `--favorite` | only favorited spaces |
| `--search <text>` | search space names |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |
| `--sort <field>` | the field to sort by |
| `--order <order>` | the sort direction |

### `contenthero space update <id>`

Rename a space or change its cover. A PATCH: a flag you omit leaves that field alone

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | space id |

| Option | Purpose |
| - | - |
| `--name <text>` | a new name |
| `--cover <url>` | a new cover image URL |
| `--no-cover` | remove the cover entirely (and its framing) |

## `stage`

### `contenthero stage create <name>`

Create a column. The slug is derived from the name and is not settable

| Argument | Required | Purpose |
| - | - | - |
| `name` | yes | column name, for example "In Review" |

| Option | Purpose |
| - | - |
| `--space <id>` | which board (from `contenthero space list`); default space if omitted |
| `--color <hex>` | a hex color such as "#3B82F6" |
| `--after <id>` | place it immediately after this item of the same list |
| `--before <id>` | place it immediately before this item of the same list |
| `--position <end>` | place it at an end of the list instead of beside an item |

### `contenthero stage delete <id>`

Delete a column and move its cards. The server refuses a non-empty column with no --target

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | stage id |

| Option | Purpose |
| - | - |
| `--space <id>` | the board this stage is on |
| `--target <id>` | where this column's cards should go (required unless it is empty) |

### `contenthero stage list`

List a space's stages, in order (defaults to the default space)

| Option | Purpose |
| - | - |
| `--space <id>` | which space's stages (from `contenthero space list`); default space if omitted |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |

### `contenthero stage update <id>`

Rename, recolor or move a column. A PATCH: a flag you omit leaves that field alone

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | stage id |

| Option | Purpose |
| - | - |
| `--space <id>` | the board this stage is on (required: an id alone does not name a board) |
| `--name <text>` | a new name; the slug follows it |
| `--color <hex>` | a new hex color |
| `--after <id>` | place it immediately after this item of the same list |
| `--before <id>` | place it immediately before this item of the same list |
| `--position <end>` | place it at an end of the list instead of beside an item |

## `tag`

### `contenthero tag create <name>`

Create a tag (the name is lowercased) (requires planner:write)

| Argument | Required | Purpose |
| - | - | - |
| `name` | yes | the tag name |

### `contenthero tag list`

List the account's tags

| Option | Purpose |
| - | - |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |

### `contenthero tag remove <id>`

Delete a tag from the account, removing it from every post (requires planner:write)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the tag id (from `tag list`) |

### `contenthero tag update <id> <name>`

Rename a tag, keeping its post assignments (requires planner:write)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the tag id (from `tag list`) |
| `name` | yes | the new tag name |

## `template`

### `contenthero template create`

Save a template of your own: from a placed code clip, code layer or shape, as a copy of a template, or from its fields

| Option | Purpose | |
| - | - | - |
| `--from-item <itemId>` | a code clip, code layer or shape placed on a project (with --from-project) | |
| `--from-project <projectId>` | the project --from-item is on | |
| `--from-template <templateId>` | a template to copy, keeping its lineage | |
| `--name <name>` | its name in the Elements panel | |
| `--category <category>` | its category: one `template list` shows, or a new one | |
| `--description <text>` | what it is for | |
| `--tag <tag>` | a word it is found by; repeatable | |
| `--code <file>` | its code, read from a file ('-' for stdin) | |
| `--lottie <url>` | a Lottie file of ours | |
| `--recolor <hex=prop>` | a color in the Lottie file that a prop recolors; repeatable | |
| `--emoji <name>` | an animated emoji's name, as the animated emoji list names it | |
| `--shape <name>` | a shape's name, as `schema layer` lists them | |
| `--props <json>` | its props as placed, as a JSON object | |
| `--props-schema <json>` | each prop's control, as a JSON object (as `template get --json` shows them) | |
| `--duration-frames <n>` | how long it lasts when placed, in frames | |
| `--coverage <coverage>` | full (the whole frame) | partial (a box of --width-fraction by --height-fraction) |
| `--width-fraction <n>` | its default width, a fraction of the canvas's | |
| `--height-fraction <n>` | its default height, a fraction of the canvas's | |
| `--resize <resize>` | scale (keeps its proportions) | reflow (lays out again in its box) |
| `--aspect <n>` | its own width over height, for --resize scale | |
| `--after <id>` | place it immediately after this item of the same list | |
| `--before <id>` | place it immediately before this item of the same list | |
| `--position <end>` | place it at an end of the list instead of beside an item | |

### `contenthero template delete <id>`

Delete one of your own templates (clips placed from it keep everything)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | template id |

### `contenthero template get <id>`

Get one template, with its code and controls

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | template id |

### `contenthero template list`

List ContentHero's templates and your own, without their code

| Option | Purpose | | |
| - | - | - | - |
| `--scope <scope>` | system | user | all (default all) |
| `--kind <kind>` | code | shape | emoji |
| `--category <category>` | only this category; repeatable | | |
| `--search <text>` | every word, in any order, in the name or the tags | | |
| `--archived` | only archived templates, to restore one | | |
| `--limit <n>` | how many to return | | |
| `--cursor <cursor>` | the previous page's cursor | | |

### `contenthero template update <id>`

Change one of your own templates, or move it among them: only the flags given

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | template id |

| Option | Purpose | |
| - | - | - |
| `--expected-version <n>` | the version you read; refused if it changed since | |
| `--name <name>` | its name in the Elements panel | |
| `--category <category>` | its category: one `template list` shows, or a new one | |
| `--description <text>` | what it is for | |
| `--tag <tag>` | a word it is found by; repeatable | |
| `--code <file>` | its code, read from a file ('-' for stdin) | |
| `--lottie <url>` | a Lottie file of ours | |
| `--recolor <hex=prop>` | a color in the Lottie file that a prop recolors; repeatable | |
| `--emoji <name>` | an animated emoji's name, as the animated emoji list names it | |
| `--shape <name>` | a shape's name, as `schema layer` lists them | |
| `--props <json>` | its props as placed, as a JSON object | |
| `--props-schema <json>` | each prop's control, as a JSON object (as `template get --json` shows them) | |
| `--duration-frames <n>` | how long it lasts when placed, in frames | |
| `--coverage <coverage>` | full (the whole frame) | partial (a box of --width-fraction by --height-fraction) |
| `--width-fraction <n>` | its default width, a fraction of the canvas's | |
| `--height-fraction <n>` | its default height, a fraction of the canvas's | |
| `--resize <resize>` | scale (keeps its proportions) | reflow (lays out again in its box) |
| `--aspect <n>` | its own width over height, for --resize scale | |
| `--after <id>` | place it immediately after this item of the same list | |
| `--before <id>` | place it immediately before this item of the same list | |
| `--position <end>` | place it at an end of the list instead of beside an item | |

## `tracked-account`

### `contenthero tracked-account get <id>`

Get one tracked account with its performance and top content

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the tracked account id |

### `contenthero tracked-account list`

List tracked accounts (both kinds by default)

| Option | Purpose |
| - | - |
| `--kind <kind>` | narrow to one kind: inspiration, brand |
| `--brand-kit <id>` | scope to the accounts linked to this brand kit |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |

### `contenthero tracked-account update <id>`

Move a tracked account within its list (requires inspiration:write)

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the tracked account id |

| Option | Purpose |
| - | - |
| `--after <id>` | place it immediately after this item of the same list |
| `--before <id>` | place it immediately before this item of the same list |
| `--position <end>` | place it at an end of the list instead of beside an item |

## `transcribe`

### `contenthero transcribe <audioUrl>`

Transcribe an audio URL to text (speech-to-text)

| Argument | Required | Purpose |
| - | - | - |
| `audioUrl` | yes | public URL of the audio to transcribe |

| Option | Purpose |
| - | - |
| `--language <code>` | ISO language hint, e.g. en (auto-detected when omitted) |
| `--diarize` | label each speaker (diarization) |

## `upscale`

### `contenthero upscale <source>`

Upscale an existing image or video to a higher resolution

| Argument | Required | Purpose |
| - | - | - |
| `source` | yes | source media (URL or output id) to upscale |

| Option | Purpose |
| - | - |
| `-m, --model <id>` | upscale model id (see `contenthero model list`) |
| `--factor <factor>` | upscale factor, e.g. 2x, 4x (model-dependent) |
| `--duration <seconds>` | source video length in seconds (required for video upscalers) |
| `--cost` | estimate the credit cost instead of upscaling |
| `--no-wait` | return the outputId immediately instead of waiting |
| `--timeout <seconds>` | how long to wait before handing back the outputId Defaults to `600`. |

## `voice`

### `contenthero voice get <id>`

Get one voice by its voiceId

| Argument | Required | Purpose |
| - | - | - |
| `id` | yes | the voice id |

### `contenthero voice list`

List saved voices (favorites first)

| Option | Purpose |
| - | - |
| `--favorite` | only favorited voices |
| `--limit <n>` | how many to return |
| `--cursor <cursor>` | the previous page's cursor |


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