AI use me

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

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

人类确认点：Agent PlanHuman checkpoint: Agent Plan

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.

安装 CLIInstall the CLI

从 npm 安装Install from npm

npm install -g seereelcli
seereelcli --help

安装 CLI 内置 AI skillInstall 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.

---
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

创建可审阅的 workflowCreate 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

更新视频节点 promptUpdate 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 审核和修复 promptOpen 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.