@soulspacex/cli

让 AI Agent 直接在 SoulSpaceX 的画布上创作：建节点、连线、生成图片和视频，产物自动落回画布。

npx @soulspacex/cli login

不用先安装——npx 直接跑。要常驻就 npm i -g @soulspacex/cli，命令名是 ssx。

五分钟跑通

ssx login                                  # 浏览器授权这台设备
ssx workflow create "短剧第一集"             # 建画布，自动绑定到当前目录

ssx node create "剧本" -t textNode \
    --prompt "写一段赛博朋克短剧的开场" \
    --model "DeepSeek V3" --run            # 建完立刻生成，阻塞到出结果

ssx node create "主视觉" -t imageNode \
    --left 剧本 --model "MJ8.2" --run      # --left 接上游，剧本的输出成为它的提示词

ssx node list                              # 每个节点的状态、模型、产物 URL、入边

最后一步之后，画布链接就在输出里，用户在网页上打开能继续编辑。

给 Agent 的几条硬约定

• 结果走 stdout（JSON），进度和提示走 stderr。 可以放心 ssx node list | jq。
• 选模型用 --model "名字"，不要手填 imageModelId 这类数字 id。 名字按节点类型解析成 id 并在输出里回显 model: {id, name}；手填的数字填错不报错，只会让画布上跑的是另一个模型。
• status / result / assetId 这类字段由生成结果回写，不要自己设，服务端会拒。拼 --set 之前先跑 ssx schema 看有哪些字段可以设。本地图片要在画布上变成能连线的图片节点，用 ssx upload 拿到 assetId 后 ssx node create 参考图 --asset <assetId>。
• 生成默认阻塞到出结果（最长 55 秒）。不要自己写 while 循环轮询——每轮一次都是一次模型调用，token 是用户在付。要立刻返回就 --wait 0。
• 节点可以用名字指代，重名时才需要用 id。
• 命令行创作按积分计费，不使用无限模式额度。
• 想让产物在网页素材库里看得到，要显式存：ssx asset save 主视觉 --category scene。分类是 character / scene / item（默认）/ voice，素材库不收视频。

命令

跑 ssx --help 看全部。常用的：

| 命令 | 作用 | | --- | --- | | ssx login / logout / whoami | 授权、登出（连带吊销服务端授权）、看余额 | | ssx workflow create/list/use/show | 画布 | | ssx node create/list/update/run/delete | 节点（list 带产物 URL、生效模型、入边） | | ssx node connect/disconnect、update --left | 连线（--left 是「入边就是这些」，重跑幂等） | | ssx generate <kind> --model <名> --prompt <描述> | 不走画布的一次性生成 | | ssx model list / ssx model search <词> | 可用模型，带 id 与计价 | | ssx schema | 节点字段契约 | | ssx upload <文件> / ssx download <url> | 素材进出（默认只拿 assetId 和 URL，不进素材库） | | ssx node create <名字> --asset <assetId> | 把上传的图落成图片节点，能连给下游 | | ssx asset save <节点名\|url> / asset list | 存进素材库、看库里有什么 | | ssx space list | 素材空间，不指定就落默认个人空间 |

环境变量

| 变量 | 说明 | | --- | --- | | SOULSPACEX_API_KEY | 直接给凭据。CI 与容器里没法交互登录，用它代替 ssx login | | SOULSPACEX_BASE_URL | 服务地址，默认 https://soulspacex.com | | SOULSPACEX_CONFIG_DIR | 凭据目录，默认 ~/.soulspacex |

本地状态

• ~/.soulspacex/credentials（0600）——凭据，跟人走。
• <项目>/.soulspacex/workflow.json——画布绑定，跟目录走，会像 git 那样逐级向上找。

谁能用

订阅卡、会员、无限模式用户。成员（子）账号不支持。会员过期后凭据即失效，续费后同一把凭据自动恢复，不用重新授权。

一个账号同时只保留一台授权设备，新设备授权会让旧设备失效。