intellistory-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

IntelliStory CLI

IntelliStory is a pre-production platform for film, TV and animation: story development, look development, storyboards, layout, AI image/video/audio generation, review. Everything lives under a workspace → project → (documents · acts/scenes · sequences/shots · assets · references · versions).

IntelliStory是面向影视与动画的前期制作平台，涵盖故事开发、视觉风格开发、分镜、布局、AI图像/视频/音频生成、审核等功能。所有内容都按工作区→项目→（文档·幕/场景·序列/镜头·资产·参考素材·版本）的层级组织。

Two ways to call the same tools

调用同一工具的两种方式

Every IntelliStory operation is a tool with a name like

list_shots

write_beats

generate_image

. There are ~200. You reach them one of two ways:

MCP — if an
```
intellistory
```
MCP server is connected in this session, call the tools directly. Same names, same arguments as below.
CLI — otherwise, run them from the shell.
```
intellistory <tool> --option value
```
is the tool call; the CLI reads the live tool registry, so anything that exists as a tool exists as a command.

Both hit the same platform with the same permissions. Prefer MCP when it's there (no process spawn); use the CLI whenever it isn't, or for anything that touches local files.

每个IntelliStory操作都是一个工具，名称类似

list_shots

、

write_beats

、

generate_image

，目前约有200个工具。你可以通过以下两种方式调用它们：

MCP — 若当前会话已连接
```
intellistory
```
MCP服务器，可直接调用工具。工具名称和参数与下文一致。
CLI — 否则，从Shell运行工具。
```
intellistory <tool> --option value
```
即为工具调用命令；CLI会读取实时工具注册表，因此所有已存在的工具都对应一个命令。

两种方式都会访问同一平台，且拥有相同权限。若MCP可用则优先使用（无需启动进程）；若不可用，或涉及本地文件操作时，请使用CLI。

Step 0 — bootstrap (CLI path)

步骤0 — 初始化（CLI路径）

bash

intellistory whoami            # signed in? which API? default project?

```
command not found
```
→
```
npm i -g intellistory
```
(Node 18+; no other dependencies).
```
Not signed in
```
→ ask the user to run intellistory login
(opens the browser, they pick a workspace, done) or, on a headless box,
```
intellistory login --with-key <key>
```
with a workspace key from Settings → API keys. Wait for them; don't guess keys.
No default project →
```
intellistory projects
```
, then
```
intellistory use <code|name|id>
```
. From then on every command that takes
```
project_id
```
fills it in;
```
--project <uuid|code|name>
```
overrides for one call.

bash

intellistory whoami            # 是否已登录？使用哪个API？默认项目是什么？

若提示
```
command not found
```
→ 执行
```
npm i -g intellistory
```
（需Node 18+；无其他依赖）。
若提示
```
Not signed in
```
→ 请用户运行**
```
intellistory login
```
**（会打开浏览器，用户选择工作区即可完成）；若在无图形界面的设备上，使用
```
intellistory login --with-key <key>
```
，其中密钥可从设置→API密钥中获取。等待用户操作，请勿猜测密钥。
若无默认项目 → 执行
```
intellistory projects
```
，然后运行
```
intellistory use <code|name|id>
```
。此后所有需要
```
project_id
```
的命令都会自动填充该值；使用
```
--project <uuid|code|name>
```
可临时覆盖一次。

Calling a tool

调用工具

bash

intellistory tools --search loom                 # find tools by name/description
intellistory help write_shot_prompt              # options, required ones marked, defaults, enums
intellistory list_shots --json                   # call — project_id injected from `use`
intellistory write_shot_prompt --shot-id <id> --prompt "…"          # dashes or underscores, either
intellistory generate_image --prompt "…" --estimate-only --json    # ask the price first
intellistory write_beats --args '{"beats":[…]}'                    # raw JSON for nested input
intellistory write_beats --args - < beats.json                     # …or from stdin

Rules the CLI enforces for you (read the error, it names the option):

options are coerced from the tool's JSON schema —
```
--limit 5
```
→ number,
```
--full
```
→ true,
```
--tags a,b
```
→ array,
```
--settings '{…}'
```
→ object;
unknown options and missing required ones exit 2 with the option name;
```
--json
```
gives compact JSON on stdout for parsing; without it you get readable JSON.
Exit codes: 0 ok · 1 the tool returned an error · 2 usage · 3 not signed in · 4 network · 5 timeout.

Wrap long-running work:

intellistory wait <job_id>

polls a generation job and exits 0 on success, 1 on failure (

--timeout 900

for long renders).

bash

intellistory tools --search loom                 # 通过名称/描述查找工具
intellistory help write_shot_prompt              # 查看选项、必填项、默认值、枚举值
intellistory list_shots --json                   # 调用工具 — project_id会从`use`命令的设置中自动注入
intellistory write_shot_prompt --shot-id <id> --prompt "…"          # 参数可使用短横线或下划线，两种格式均支持
intellistory generate_image --prompt "…" --estimate-only --json    # 先估算成本
intellistory write_beats --args '{"beats":[…]}'                    # 使用原始JSON作为嵌套输入
intellistory write_beats --args - < beats.json                     # …或从标准输入读取

CLI会为你强制执行以下规则（若出错，错误信息会指明具体选项）：

选项会根据工具的JSON Schema自动转换类型 —
```
--limit 5
```
→ 数字类型，
```
--full
```
→ 布尔值true，
```
--tags a,b
```
→ 数组类型，
```
--settings '{…}'
```
→ 对象类型；
未知选项或缺失必填选项会以退出码2终止，并提示选项名称；
```
--json
```
参数会在标准输出生成紧凑的JSON格式以便解析；不使用该参数则输出可读性更强的JSON。
退出码：0=成功 · 1=工具返回错误 · 2=使用错误 · 3=未登录 · 4=网络错误 · 5=超时。

对于长时间运行的任务：

intellistory wait <job_id>

会轮询生成任务的状态，成功则以退出码0终止，失败则以退出码1终止（

--timeout 900

可设置长渲染任务的超时时间）。

Local files ↔ the project (CLI only — MCP can't see the disk)

本地文件 ↔ 项目（仅CLI支持 — MCP无法访问磁盘）

bash

intellistory upload ./takes/*.mp4 --shot sq010_sh0020 --pass-type previz     # versions on a shot
intellistory upload ./board.png --shot sq010_sh0020 --pass-type storyboard
intellistory upload ./moodboard/*.jpg --ref --category mood --tags night,rain # project references
intellistory upload ./cleo_front.png --character "Cleo"                       # onto a character
intellistory download sq010_sh0020 -o ./renders/                              # newest version on the shot
intellistory download <file_id> -o ./x.mp4        # a specific version;  --all for every version

Uploads are ≤ 36 MB per file for now — for a longer render, upload a shorter or lower-bitrate encode rather than an external link. Video must have its audio muxed in before upload; the platform plays exactly the bytes you send.

pass_type

is the production STAGE: images →

storyboard

concept

; video →

previz

animatic

final

; audio →

vo

bash

intellistory upload ./takes/*.mp4 --shot sq010_sh0020 --pass-type previz     # 上传到镜头的版本
intellistory upload ./board.png --shot sq010_sh0020 --pass-type storyboard
intellistory upload ./moodboard/*.jpg --ref --category mood --tags night,rain # 上传到项目参考素材
intellistory upload ./cleo_front.png --character "Cleo"                       # 上传到角色
intellistory download sq010_sh0020 -o ./renders/                              # 下载镜头的最新版本
intellistory download <file_id> -o ./x.mp4        # 下载特定版本；使用--all可下载所有版本

目前单文件上传大小限制为≤36 MB — 若要上传长渲染文件，请上传较短或低码率的编码文件，而非外部链接。视频文件上传前必须合并音频；平台会直接播放你上传的原始字节内容。

pass_type

对应制作阶段：图片→

storyboard

（分镜）/

concept

（概念图）；视频→

previz

（预演）/

animatic

（动态分镜）/

final

（最终版）；音频→

vo

（旁白）。

IDs — the one thing that goes wrong most

ID — 最容易出错的地方

Four different things are called an "id" (

references/ag-ids-and-refs.md

). In short:

UUID = the row. Most write tools also accept a reference code (
```
sq010_sh0020
```
,
```
CHAR_CLEO
```
) and resolve it for you — pass codes, don't guess UUIDs.
@-IDs (
```
@S4
```
,
```
@C1
```
) inside scripts are a registry:
```
register_element
```
with the canonical name and use exactly what comes back; never invent one; never strip them when editing.
Shots, assets and versions return an
```
app_url
```
— give the user that (or
```
create_share_link
```
), not a raw media URL.

有四种不同的“id”（详见

references/ag-ids-and-refs.md

）。简言之：

UUID = 数据行标识。大多数写入工具也接受参考代码（如
```
sq010_sh0020
```
、
```
CHAR_CLEO
```
）并自动解析 — 请传递代码，不要猜测UUID。
脚本中的**@-IDs**（如
```
@S4
```
、
```
@C1
```
）属于注册标识：使用
```
register_element
```
命令注册规范名称，并严格使用返回的标识；请勿自行创建，编辑时也请勿删除。
镜头、资产和版本会返回
```
app_url
```
— 请将该链接（或使用
```
create_share_link
```
生成的链接）提供给用户，而非原始媒体URL。

Connecting an agent (one command each)

连接Agent（每个Agent对应一条命令）

bash

intellistory setup claude-code      # claude mcp add … (user scope)
intellistory setup claude-desktop   # stdio proxy — no key lands in the config
intellistory setup cursor | codex | gemini | hermes | openclaw
intellistory setup <agent> --print  # show what would be written, write nothing
intellistory skills install         # npx skills add AlienrobotLLC/intellistory-skills

intellistory mcp

is the stdio MCP proxy those setups use; it adds one local-only tool,

stash_pasted_images

, that files images the user pasted into chat as project references.

bash

intellistory setup claude-code      # claude mcp add …（用户范围）
intellistory setup claude-desktop   # 标准输入输出代理 — 密钥不会存储到配置中
intellistory setup cursor | codex | gemini | hermes | openclaw
intellistory setup <agent> --print  # 显示将要写入的内容，但不实际写入
intellistory skills install         # npx skills add AlienrobotLLC/intellistory-skills

intellistory mcp

是上述设置所使用的标准输入输出MCP代理，它会添加一个仅本地可用的工具

stash_pasted_images

，用于将用户粘贴到聊天中的图片保存为项目参考素材。

Behaviour

操作规范

Describe what happened, not the plumbing: "boarded six shots of sq020" — not the model routing or the queue. Don't narrate "calling the CLI".

Money is real:

generate_*

and

regenerate_sequence

take

estimate_only: true

— quote, get a yes, then run (

references/ag-billing.md

Read before you write on an existing project:
```
read_cortex
```
gives the whole state.
After a batch of meaningful story/structure changes, call
```
invalidate_cortex
```
once.
When a read comes back empty, check project → entity code → upstream exists → stale view, in that order (
```
references/ag-failure-modes.md
```
). Don't invent an ID, a price or a capability;
```
list_knowledge_base
```
/
```
read_knowledge_article
```
are authoritative for platform questions.

描述实际执行的操作，而非底层流程：比如“完成了sq020的6个镜头分镜” — 不要描述模型路由或队列相关内容，也不要提及“调用CLI”。
费用是真实产生的：
```
generate_*
```
和
```
regenerate_sequence
```
支持
```
estimate_only: true
```
参数 — 先报价，获得用户同意后再执行（详见
```
references/ag-billing.md
```
）。
在现有项目中写入内容前，请先读取：
```
read_cortex
```
命令会返回项目的完整状态。
在完成一批重要的故事/结构修改后，请调用一次
```
invalidate_cortex
```
。
当读取结果为空时，请按以下顺序排查：项目→实体代码→上游是否存在→视图是否过期（详见
```
references/ag-failure-modes.md
```
）。请勿自行创建ID、价格或功能；
```
list_knowledge_base
```
/
```
read_knowledge_article
```
是解答平台相关问题的权威途径。

References

参考文档

references/cli-reference.md

— full command list (generated from

intellistory --help

)

```
references/ag-ids-and-refs.md
```
— UUIDs vs codes vs @-IDs vs deep links
```
references/ag-failure-modes.md
```
— the silent no-ops and how to read an empty result
```
references/ag-billing.md
```
— estimate-first, credits, what to tell the user

references/cli-reference.md

— 完整命令列表（由

intellistory --help

生成）

```
references/ag-ids-and-refs.md
```
— UUID、代码、@-IDs与深度链接的区别
```
references/ag-failure-modes.md
```
— 静默无操作的情况及如何解读空结果
```
references/ag-billing.md
```
— 先估算、 credits、需告知用户的信息