SeeReel Agent CLI

# AI use me

这个页面写给 Codex、Claude Code、Cursor Agent 和其他本地 AI Agent。用 CLI 把人类的视频创意变成网页上可见的 SeeReel workflow；只有在人类完成 Agent Plan 配置后，才继续付费生成。 This page is written for Codex, Claude Code, Cursor Agent, and other local AI agents. Use the CLI to turn a human video idea into a visible SeeReel web workflow, then continue generation only after the human has configured Agent Plan access.

## Agent 启动步骤 Agent bootstrap

如果你是正在读这个页面的 AI Agent，先运行下面几行。它会安装 CLI 和内置操作 skill，并确认你能看到 SeeReel workflow 命令。 If you are an AI agent reading this page, run this first. It installs the CLI and the bundled operating skill, then verifies that you can see the SeeReel workflow commands.

    npm install -g seereelcli
    seereelcli skill install --agent all
    seereelcli skill print
    seereelcli --help

当前会话提示。Current thread note. 安装 skill 能让之后的 Codex / Claude Code / Cursor 会话自动加载 SeeReel 流程。在当前已经运行的会话里，请直接阅读 `seereelcli skill print` 并按它执行。 Installing a skill helps future Codex / Claude Code / Cursor sessions auto-load the SeeReel procedure. In the same running thread, read `seereelcli skill print` and follow it directly.

## AI 可以做什么 What you are allowed to do

创建 workflow Create the workflow

创建 session，把自然语言视频想法写成 logline，生成剧本，并生成网页 UI 里可见的分镜 workflow。Create a session, write the natural-language idea as the logline, generate the script, and generate storyboard shots visible in the web UI.

让人类接管 Let the human take over

返回 session URL，让人类在网页里修改剧本、prompt、资产、镜头时长、参考图和生成策略。Return the session URL so the human can edit script, prompts, assets, shot durations, references, and generation choices.

继续生成视频 Continue to video

在人类确认 key 和 prompt 选择后，再通过 SeeReel API 生成缺失镜头并拼接最终视频。After the human confirms credentials and prompt choices, render missing shots and stitch the final video through SeeReel APIs.

## 人类确认点：Agent Plan Human checkpoint: Agent Plan

不要编造、抓取或暴露 API Key。Do not invent, scrape, or expose API keys. 必须由人类自己开通并支付 Agent Plan，然后自己输入 key。 The human must open and pay for Agent Plan, then enter the key themselves.

1. 请人类打开 Volcengine Agent Plan，并在 Ark 控制台创建 Agent Plan API key。Ask the human to open Volcengine Agent Plan and create an Agent Plan API key in the Ark console.
2. 请人类打开 https://seereel.studio/，点击顶部 Agent Plan 按钮，把 key 粘贴进去，供浏览器手动生成使用。Ask the human to open https://seereel.studio/, click the top-bar Agent Plan button, and paste the key for browser/manual generation.
3. 如果要让 CLI 自动化继续生成，CLI 自己的本地用户作用域也需要 key。请人类亲自运行 configure 命令，或在 agent 运行环境里设置 `SEEREEL_AGENT_PLAN_TOKEN`。For CLI automation, the CLI also needs the key in its own local user scope. Ask the human to run the configure command themselves, or set `SEEREEL_AGENT_PLAN_TOKEN` in the agent runtime environment.

    seereelcli configure --base-url https://seereel.studio --agent-plan-token "<human-pastes-key-here>"

浏览器 key 和 CLI key 是分开的，因为 SeeReel 按 cookie 隔离访问者。把这个隔离当成安全边界；当人类需要在浏览器里接管 CLI 创建的 session 时，返回 `handoffUrl`。 The browser key and CLI key are separate because SeeReel isolates visitors by cookie. Treat that isolation as a safety feature, and use `handoffUrl` when a human should claim a CLI-created session for browser editing.

## 安装 CLI Install the CLI

### 从 npm 安装 Install from npm

    npm install -g seereelcli
    seereelcli --help

### 安装 CLI 内置 AI skill Install the AI skill bundled with the CLI

    seereelcli skill install --agent all
    seereelcli skill print

npm 包包含 `seereel-cli` skill。安装后，Codex、Claude Code、Cursor Agent 和其他本地 agent runtime 会获得安全使用 CLI 的操作流程。 The npm package includes the `seereel-cli` skill. Installing it gives Codex, Claude Code, Cursor Agent, and other local agent runtimes the operating procedure for using the CLI safely.

无法立刻安装时，给 AI Agent 直接阅读的内置 skill 源码 Bundled skill source for AI agents that cannot install immediately

    ---
    name: seereel-cli
    description: Use the local SeeReel CLI to create, inspect, edit, render, review, repair, and stitch web-visible SeeReel video workflows from natural language. Trigger when the user asks an AI agent to use SeeReel, seereel.studio, the SeeReel CLI, generate a web workflow, operate a shot/node prompt, generate a tailframe, run VLM review, repair prompts, publish storyboards to TOS, or produce a complete video through the site.
    ---

    # SeeReel CLI

    Use this skill when the user wants an AI agent to operate SeeReel through the local CLI instead of manually clicking the web UI.

    SeeReel has two surfaces:

    - Web app: human review and takeover surface.
    - CLI/API: agent operation surface. Everything important must remain visible in the web app.

    ## Human Credential Boundary

    Do not invent, request from hidden memory, scrape, or expose API keys.

    For real generation, the human must:

    1. Open/pay for Volcengine Agent Plan.
    2. Create an Agent Plan API key in Ark.
    3. Paste it into the SeeReel web top-bar Agent Plan control for browser/manual work.
    4. For CLI automation, either run:

    ```bash
    seereelcli configure --base-url https://seereel.studio --agent-plan-token "<human-pastes-key-here>"
    ```

    or set `SEEREEL_AGENT_PLAN_TOKEN` / `ARK_AGENT_PLAN_KEY` in the AI runtime environment.

    Browser credentials and CLI credentials are cookie-scoped separately. Treat that isolation as intentional. A raw `webUrl` belongs to the CLI cookie scope; return `handoffUrl` when a human needs to open and continue editing the AI-created workflow in a normal browser.

    ## Install

    If the npm package is published:

    ```bash
    npm install -g seereelcli
    seereelcli skill install --agent all
    ```

    The npm package bundles this skill. `seereelcli skill install --agent all` copies it into local Codex, Claude, Cursor, and generic `.agents` skill folders. `seereelcli skill print` prints the bundled `SKILL.md` when an agent needs to read or mirror it manually.

    Current repo-local install:

    ```bash
    git clone https://github.com/feifeibear/seereel-agent.git
    cd seereel-agent
    npm install
    npm install -g ./packages/seereel-cli
    seereelcli --help
    ```

    From repo root without global install:

    ```bash
    npm run cli -- --help
    ```

    ## Configure

    Default base URL is `https://seereel.studio`.

    ```bash
    seereelcli configure --base-url https://seereel.studio
    ```

    If the deployment requires a shared access token:

    ```bash
    seereelcli configure --access-token "$SEEREEL_ACCESS_TOKEN"
    ```

    For local development:

    ```bash
    seereelcli configure --base-url http://localhost:5173
    ```

    ## Review-First Default Flow

    Default: create a visible workflow, then stop for human review.

    ```bash
    seereelcli workflow "一个失眠导演在午夜便利店遇见未来的自己" \
      --duration 60 \
      --style "neo-noir, rain reflections, grounded sci-fi" \
      --json
    ```

    Return the one-time `handoffUrl` to the user, not the raw `webUrl`. It should look like:

    ```text
    https://seereel.studio/api/handoff/xxxxxxxx
    ```

    Tell the human the handoff link transfers the session from the CLI cookie identity to their current browser identity, then they can edit script, shot prompts, assets, duration, references, and generation choices in the web UI. After a handoff is claimed, keep using the browser/web UI as source of truth unless the human asks you to continue from a CLI-owned session.

    ## Full Video Flow

    Only continue after the human confirms Agent Plan is configured and the workflow is acceptable.

    ```bash
    seereelcli status --session latest --deep --json
    seereelcli render --session latest --stitch --progress --json
    ```

    If the human explicitly asks for full automation:

    ```bash
    seereelcli workflow "用户的视频创意" --duration 60 --render --stitch --jsonl
    ```

    Report the final `downloadUrl`. If a shot fails, report the shot id and failure; do not silently skip it. Use `--stitch-partial` only when the human accepts a shorter cut made from ready shots.

    Download locally with:

    ```bash
    seereelcli download --session latest --output ./final.mp4
    ```

    ## Node Operations

    Inspect one node:

    ```bash
    seereelcli node get --id shot_xxxxxxxx --json
    seereelcli node get --id asset_xxxxxxxx --json
    seereelcli node get --id ses_xxxxxxxx --json
    ```

    Update a video node prompt:

    ```bash
    seereelcli node update-prompt --id shot_xxxxxxxx \
      --prompt "新的 Seedance 视频 prompt，保留角色服装和场景连续性" \
      --title "03 重新追上自己" \
      --duration 15 \
      --json
    ```

    Generate or poll one video node:

    ```bash
    seereelcli node generate --id shot_xxxxxxxx --wait --json
    seereelcli node poll --id shot_xxxxxxxx --json
    ```

    Generate a rendered shot tailframe:

    ```bash
    seereelcli node tailframe --id shot_xxxxxxxx --publish-tos --canvas-node --json
    ```

    Use `--publish-tos` when the tailframe will be used as a Seedance reference. Seedance cannot fetch local `/media/...` URLs.

    Open VLM review and repair:

    ```bash
    seereelcli node review --id shot_xxxxxxxx --frame-count 8 --json
    seereelcli node repair --id shot_xxxxxxxx --json
    seereelcli final-review --session latest --json
    seereelcli final-review --session latest --repair --json
    ```

    Operate asset nodes:

    ```bash
    seereelcli node update-prompt --id asset_xxxxxxxx --prompt "角色参考图 prompt" --json
    seereelcli node generate --id asset_xxxxxxxx --model seedream-5-lite --json
    seereelcli node review --id asset_xxxxxxxx --json
    ```

    Publish storyboard references to TOS:

    ```bash
    seereelcli publish-storyboards --session latest --json
    ```

    ## Rules

    - Prefer CLI/API over browser automation.
    - Always use `--json` when you need to parse results.
    - Use `--jsonl` or `--progress` for long render/stitch runs so the agent can observe progress without polling `/api/state` in another shell.
    - Refresh status before continuing after a human web edit.
    - Browser credentials and CLI credentials are cookie-scoped separately. Raw `webUrl` may not be visible in a bare browser; use `seereelcli handoff --session latest --json` and return the one-time `handoffUrl` for human takeover.
    - Do not call paid generation before Agent Plan is configured and the human has approved continuing.
    - Keep local scratch media out of the final story; SeeReel web state is the source of truth.
    - For Seedance references, only remote `http(s)` URLs are valid. Publish local references to TOS first.

### 仓库本地兜底安装 Repo-local fallback

    git clone https://github.com/feifeibear/seereel-agent.git
    cd seereel-agent
    npm install
    npm install -g ./packages/seereel-cli
    seereelcli skill install --agent all

## 创建可审阅的 workflow Create a reviewable workflow

从这里开始。风险较低，因为它只创建网页可见的规划节点，并会在付费视频生成前停下。Start here. This is low risk because it creates visible planning nodes and stops before paid video rendering.

    seereelcli workflow "一个失眠导演在午夜便利店遇见未来的自己" \
      --base-url https://seereel.studio \
      --duration 60 \
      --style "neo-noir, rain reflections, grounded sci-fi" \
      --json

把一次性的 `handoffUrl` 返回给人类，不要返回原始 `webUrl`。它看起来像这样：Return the one-time `handoffUrl` to the human, not the raw `webUrl`. It should look like:

    https://seereel.studio/api/handoff/xxxxxxxx

handoff 链接会把 CLI 创建的 session 转移到当前浏览器 cookie 下，让人类继续编辑 AI 生成的 workflow。The handoff link transfers the CLI-created session to the current browser cookie so the human can continue editing the AI workflow.

## 生成完整视频 Generate the full video

只有在人类确认 Agent Plan 已配置，并且网页 workflow 看起来可接受后，才继续。Only continue after the human confirms Agent Plan is configured and the web workflow looks acceptable.

    seereelcli status --session latest --deep --json
    seereelcli render --session latest --stitch --progress --json

如果人类明确要求全自动，也可以一次性创建、生成并拼接：Or create, render, and stitch in one run when the human explicitly asks for full automation:

    seereelcli workflow "用户的视频创意" --duration 60 --render --stitch --jsonl

持续等待，直到 CLI 返回最终 `downloadUrl`。如果某个 shot 失败，报告失败 shot id，让人类编辑或要求你重试。只有在人类接受用已完成镜头拼较短版本时，才使用 `--stitch-partial`。 Poll until the CLI returns a final `downloadUrl`. If a shot fails, report the failed shot id and let the human edit or ask you to retry. Use `--stitch-partial` only when the human accepts a shorter cut from ready shots.

### 恢复流程 Recovery runbook

    seereelcli status --session latest --deep --json
    seereelcli node poll --id shot_xxxxxxxx --json
    seereelcli node update-prompt --id shot_xxxxxxxx --prompt "safer Seedance prompt" --duration 8 --json
    seereelcli render --session latest --repair-policy safe-retry --max-attempts 2 --stitch-partial --progress --json

### 下载到本地 Download locally

    seereelcli download --session latest --output ./final.mp4

## 更细粒度的节点操作 Fine-grained node operations

当人类已经在网页编辑 workflow，或要求你精确操作某个画布节点时，用这些命令。Use these when the human edits the workflow or asks you to operate one canvas node precisely.

### 查看一个节点 Inspect one node

    seereelcli node get --id shot_xxxxxxxx --json
    seereelcli node get --id asset_xxxxxxxx --json
    seereelcli node get --id ses_xxxxxxxx --json

### 更新视频节点 prompt Update a video node prompt

    seereelcli node update-prompt --id shot_xxxxxxxx \
      --prompt "新的 Seedance 视频 prompt，保留角色服装和场景连续性" \
      --title "03 重新追上自己" \
      --duration 15 \
      --json

### 生成或轮询单个视频节点 Generate or poll a single video node

    seereelcli node generate --id shot_xxxxxxxx --wait --json
    seereelcli node poll --id shot_xxxxxxxx --json

### 生成镜头尾帧 Generate a shot tailframe

    seereelcli node tailframe --id shot_xxxxxxxx --publish-tos --canvas-node --json

当尾帧要作为 Seedance 参考图使用时，加上 `--publish-tos`。远端 Seedance 无法读取本地 `/media/...` URL。 Use `--publish-tos` when the tailframe will become a Seedance reference. Remote Seedance cannot fetch local `/media/...` URLs.

### 开启 VLM 审核和修复 prompt Open VLM review and repair prompts

    seereelcli node review --id shot_xxxxxxxx --frame-count 8 --json
    seereelcli node repair --id shot_xxxxxxxx --json
    seereelcli final-review --session latest --json
    seereelcli final-review --session latest --repair --json

### 资产和故事板 Assets and storyboards

    seereelcli node update-prompt --id asset_xxxxxxxx --prompt "角色参考图 prompt" --json
    seereelcli node generate --id asset_xxxxxxxx --model seedream-5-lite --json
    seereelcli node review --id asset_xxxxxxxx --json
    seereelcli publish-storyboards --session latest --json

## AI Agent 操作规则 Operational rules for AI agents

- 以 SeeReel API/CLI 状态作为事实来源。不要把生成媒体藏在私有临时目录里。Use SeeReel API/CLI state as the source of truth. Do not hide generated media in private scratch folders.
- 人类在网页做过任何编辑后，继续前必须刷新状态。Refresh status before continuing after any human web edit.
- 长时间 render 使用 `--progress` 或 `--jsonl`，不要再开一个 shell 通过 `/api/state` 猜进度。Use `--progress` or `--jsonl` for long render runs instead of opening a second shell to guess progress from `/api/state`.
- 浏览器 session 和 CLI session 按 cookie 分开；普通浏览器可能看不到原始 `webUrl`，因此人类接管时返回 `handoffUrl`。Browser and CLI sessions are cookie-scoped separately; raw `webUrl` may not be visible in a normal browser, so return `handoffUrl` for human takeover.
- Agent Plan 未配置、且人类未批准继续前，不要调用付费视频生成。Do not call paid video generation until Agent Plan is configured and the human has approved continuing.
- 本地开发时，把 base URL 换成 `http://localhost:5173` 或设置 `SEEREEL_AGENT_BASE_URL`。For local development, replace the base URL with `http://localhost:5173` or `SEEREEL_AGENT_BASE_URL`.
- 如果公网后端需要共享访问 token，使用 `SEEREEL_ACCESS_TOKEN` 或 `--access-token`。If the public backend requires a shared access token, use `SEEREEL_ACCESS_TOKEN` or `--access-token`.