The open creative studio on ComfyUI: images, video, 3D and audio on open weights, on your own GPU or the cloud. Camera motions, effects, apps, Cinema, Layers, Image to 3D and an AI agent.
The fuobe command line
fuobe makes images, video, audio, 3D and text with a Fuobe server from a terminal, a script or a
coding agent. It talks to the server's REST API (and its MCP endpoint for the studio tools), so
everything it starts shows up in the Library like any other job, on the cloud or the open-source
engine. It is plain Node (20 or later) with no dependencies: bin/fuobe.mjs and bin/lib/.
fuobe generate "a red fox in fresh snow, golden hour" --out renders/
Install
In a Fuobe checkout (the folder you run the server from):
npm link # puts `fuobe` on your PATH; it links bin/fuobe.mjs, nothing is installed
fuobe --version
ln -s "$PWD/bin/fuobe.mjs" ~/.local/bin/fuobe does the same by hand. On another machine you only
need the bin folder and package.json:
git clone --depth 1 --sparse https://github.com/workingprototype/Fuobe fuobe-cli
cd fuobe-cli && git sparse-checkout set bin && npm link
Or run it in place with node bin/fuobe.mjs ….
Connect to a server
The CLI finds its server and token in this order:
| server | token | |
|---|---|---|
| 1 | --url |
--token |
| 2 | FUOBE_URL |
FUOBE_TOKEN |
| 3 | the file fuobe login saved |
the same file, for that server only |
| 4 | http://localhost:3000 |
none |
The saved token goes only to the server it was saved with. A --url or FUOBE_URL that names
another server gets no token unless you pass --token or set FUOBE_TOKEN (those two go to
whichever server the command talks to); fuobe status says when the saved token was left out.
A Fuobe without a password (the default for local use) needs no token. Once a password is set, the
CLI needs an API token: open Settings → Security → API tokens in the browser
(http://localhost:3000/settings#security), create one and copy it. It starts with fuobe_ and is
shown once.
fuobe login
# Fuobe server [http://localhost:3000]: studio.lan:3000
# This Fuobe has a password. Create an API token in Settings → Security → API tokens … and paste it here.
# API token: ········
# Signed in to http://studio.lan:3000 with an API token.
fuobe login --url https://studio.example.com --token fuobe_… # without questions (scripts, CI)
fuobe status # where it points, and whether the token works
fuobe logout # forget the saved address and token
fuobe login checks the address and the token before saving them to
~/.config/fuobe/config.json ($XDG_CONFIG_HOME/fuobe/config.json when that is set, or
FUOBE_CONFIG). The folder is created readable by you only (0700) and the file is written 0600.
Commands
Every command takes --json (machine-readable output on stdout; errors as {"error": …, "status": …}
on stderr), --url, --token and --help. fuobe <command> --help lists its options.
fuobe models — what you can run
fuobe models --kind video --engine open # open-source video models (ComfyUI)
fuobe models --search kling # every word must match the name, vendor, what it does or the id
fuobe models --op tts --json # models that run one operation, with voices, sizes and lengths
fuobe models --hidden # also the helper models studios use behind the scenes
--kind is image, video, audio, text or model3d; --engine is open or cloud. The
price says how a run goes today, following Settings → Placeholder results: "(demo)" runs but returns placeholder
media for free (placeholder results are on); "(not set up)" won't run until its
provider is set up. --json gives the same as runs (real, demo or
refused) per model. An install set to one engine only (Settings → Engine mode) lists that
engine's models only.
fuobe estimate — price a run first
Takes the same options as generate and starts nothing. Local files aren't uploaded to price a run.
fuobe estimate "a fox in the snow" --model nano-banana-pro --count 4
# Nano Banana Pro (cloud) · Text to image · 4 images · about $0.60
fuobe estimate "slow push-in" --model kling-3 --image still.png --duration 10
fuobe generate — make something
fuobe generate "a red fox in fresh snow, golden hour" --wait # the Image studio's model; prints the URLs
fuobe generate "make it blue" --image photo.jpg --engine open --out . # an edit on the open engine, saved here
fuobe generate "she turns and smiles" --model kling-3 --image portrait.jpg \
--aspect 9:16 --duration 5 --out renders/ # image to video
fuobe generate "Welcome to the studio." --kind audio --out audio/ # speech (ElevenLabs v4)
fuobe generate "Hello there." --kind audio --voice-audio me.wav --wait # in your voice (Chatterbox; --engine open runs it on ComfyUI)
fuobe generate --model oss-join-clips --video a.mp4 --video b.mp4 --out . # join two clips
fuobe generate "make it rain" --model kling-o3 --video clip.mp4 --wait # edit a video
echo "a long prompt…" | fuobe generate - --model seedance-2-5 --wait # the prompt from stdin
With no --model, the studio's own pick is used and named on stderr: --kind image (the default;
the Edit studio's model when you pass --image), video or audio, on --engine (else the cloud,
unless the install runs open source only). With --kind audio, a --voice-audio sample picks a
model that clones it (chatterbox-cloud, or oss-chatterbox on the open engine), and two samples
pick the open dialogue model (oss-chatterbox-dialogue; no cloud dialogue model clones voices). A
model named with --model that would ignore a sample (premade voices only, or one speaker for two
samples) is refused with a sentence instead. Any other video or audio input needs --model,
because many kinds of model take one (edit, extend, lip-sync, transcribe…).
| option | goes to |
|---|---|
-m, --model <id> |
the model (fuobe models) |
--op <op> |
the operation when the inputs leave it open (t2i, edit, i2v, t2v, flf2v, ref2v, extend, tts, transcribe, translate, trim, mux…) |
-i, --image <file|url> |
the image to edit, the start frame, or references (repeat, up to 14) |
--end-image, --mask |
the end frame; an inpaint mask |
--video <file|url> |
the video to edit, extend, trim or lip-sync; two or more are clips to join |
--ref-video, --ref-audio |
reference clips (reference to video) |
--audio, --background-audio |
a voice track, a soundtrack, a recording to transcribe; a second track mixed under it |
--voice-audio <file> |
a voice to clone or change into (twice for a dialogue's two speakers) |
-a, --aspect, -r, --resolution, -d, --duration |
16:9, 1080p, seconds |
-n, --count <n> |
takes (1–8) |
--seed, --negative, --sound / --no-sound, --enhance |
seed, negative prompt, native sound, prompt rewriting |
--voice <id>, --language, --source-language |
a premade voice; the language to translate or dub into; the spoken one |
--start, --end |
trim points in seconds |
-p, --param key=value |
any other model setting (numbers, booleans and JSON are read as such; unknown keys go to params.extra) |
-w, --wait / -o, --out <dir> |
wait and print the results / wait and save the files |
--timeout, --interval |
how long to wait (default 1800 s, 0 = no limit) and how often to check (default 2 s) |
Inputs can be local files, https:// links or /api/files/… URLs from earlier results. Local files
are uploaded through /api/uploads first (up to 200 MB each; a file named twice is uploaded once),
after every file has been found and the request has been checked, so a missing input fails before
a big upload. Downloads are named <id>.<ext> (<id>-<n>.<ext> for several outputs) and always
land in --out. When the server can't run a request it says what's missing, and the CLI names the
option: Add a portrait and a voice track (use --image <file|url> and --audio <file|url>).
Without --wait or --out, generate prints the job ids and returns at once.
fuobe status, fuobe wait, fuobe download, fuobe cancel
fuobe status # the server: engine mode, placeholder results, providers, the local LLM, the token
fuobe status V1StGXR8_Z5j # one or more generations
fuobe wait V1StGXR8_Z5j 3Kp9x2LmQa7c # until each is done; prints the output URLs (text results inline)
fuobe wait V1StGXR8_Z5j --out renders/
fuobe download V1StGXR8_Z5j --out renders/ # waits first; --no-wait fails if it isn't finished
fuobe cancel V1StGXR8_Z5j
Files are saved as <id>.<ext> (<id>-1.png, <id>-2.png… when a job has several outputs). On a
terminal, waiting shows one progress line; Ctrl+C stops waiting, not the job.
fuobe list — your recent generations
fuobe list --kind video --limit 5
fuobe list --status failed --json
fuobe list --search "red fox" --model nano-banana-pro
fuobe upload — files to pass by URL
fuobe upload product.png # prints /api/files/uploads/…/….png
Useful for MCP tools and fuobe tool, which take URLs.
fuobe skills — Assist skills
fuobe skills list # built-in and yours, on or off
fuobe skills show katana # the SKILL.md
fuobe skills disable katana # Assist and MCP clients stop offering it
fuobe skills enable katana
fuobe skills add ./my-skill # a folder with a SKILL.md (and its text files)
fuobe skills add launch-video.zip # a .zip or .skill archive, or a SKILL.md
fuobe skills add owner/repo --skill launch-video # one skill from a GitHub repository
fuobe skills add https://github.com/owner/repo/tree/main/skills/launch-video
fuobe skills add ./my-skills --replace # overwrite your own skills of the same names
add finds skills the way the open skills CLI does: the folder itself when it holds a SKILL.md,
else skills/, .agents/skills/, .claude/skills/ and the folders right under it (up to three
levels), else any SKILL.md a few levels down; skills marked metadata.internal: true are left out
unless named with --skill. Each skill is uploaded as a zip with its text files (binaries and
dot-files are left out, and listed). Git sources need git. A skill's recipe.json (a skill that runs
by itself; see skills/README.md) goes up with it but starts untested: skills run prices every step
for free before its first run (nothing runs), or give it a free Test run in Assist → Skills
(every step priced and run once with placeholder results; nothing runs for real).
Running a skill that runs by itself
A skill with a recipe runs its saved steps with new inputs, with no AI model planning them: priced first, the same steps every time.
fuobe skills params weekly-promo # its inputs: id, type, needed or default, what it takes
fuobe skills estimate weekly-promo -p product=lamp.png -p name="Lumen desk lamp"
fuobe skills run weekly-promo -p product=lamp.png -p name="Lumen desk lamp" --wait
fuobe skills run weekly-promo --rows products.csv --engine cloud --out renders/
fuobe skills export weekly-promo --out weekly-promo.zip # SKILL.md and its files, to add elsewhere
-p input=valuegives one input (repeat it;fuobe skills paramslists the ids). A file input takes a local file, anhttps://link or a/api/files/…URL. Local files are uploaded only when it runs:estimateprices with stand-ins, asfuobe estimatedoes.--rows rows.csvruns it once per row (up to 50;-reads the table from stdin). The first row names the inputs by id or label, as the Many tab of the Run dialog reads it; a spreadsheet's paste (tabs) works too. A file path in a cell is read from the table's folder, and each file goes up once.-pfills what the rows leave empty. A row that doesn't fit is named by its line, and then nothing starts.runprices the whole batch first and asksRun 20 for $12.40? [y/N]when it costs money.--yesstarts it without asking;--jsonalone doesn't (a script adds--yes). Without a terminal to ask on, it stops and says to add--yes. Free runs (your GPU, or a demo) start without asking. Once your files are uploaded it prices them again (a clip is priced by its length): when that's more, it asks again with the new price, or stops without a terminal.--engine open|cloudpicks where it runs, among the engines its steps run on (by default: where it was tested). A skill not yet priced on that engine has every step priced first, for free (nothing runs).--waitand--out <dir>wait for the results and save them, asfuobe generatedoes; without them,runprints the ids to pass tofuobe waitorfuobe download. When a row didn't start (a studio tool's run can refuse one row and start the rest), it says which by its line in your file and exits 1;--jsonlists every run underruns, each with itserrorand, for--rows, itsline.exportsaves the skill as a zip (SKILL.md,recipe.jsonand its other files);--exampleskeeps the values it was made with, which are left out by default.
fuobe tools, fuobe tool — the MCP tools
The studio jobs (Katana, dubbing, Faceless episodes, Layers, ads, captions…) are MCP tools. The CLI can call them without an MCP client:
fuobe tools # the list
fuobe tool katana --schema # what it takes
fuobe tool search_models --arg kind=video --arg query=kling
fuobe tool estimate_job '{"tool": "katana", "arguments": {"reference": "/api/files/…", "photos": ["/api/files/…"]}}'
echo '{"ids": ["V1StGXR8_Z5j"], "wait_seconds": 60}' | fuobe tool check_generations -
fuobe mcp — connect an agent
fuobe mcp
# claude mcp add --transport http fuobe http://localhost:3000/api/mcp
Run the printed line to add Fuobe to Claude Code. With a token, the line carries
--header "Authorization: Bearer fuobe_…"; keep it out of shared places. Other MCP clients (Claude
Desktop, Cursor, Codex…) take the server entry it prints on stderr (fuobe mcp --json gives both):
{ "mcpServers": { "fuobe": { "type": "http", "url": "http://localhost:3000/api/mcp", "headers": { "Authorization": "Bearer fuobe_…" } } } }
The agent then has search_models, estimate_cost, generate, check_generations, the studio
tools and Fuobe's skills as prompts.
fuobe eval — measure the Fuobe Originals
From a Fuobe checkout, fuobe eval <command> is the evaluation harness (pnpm eval:<command>). It
finds the server and token as the other commands do, so the saved token goes only to the server it was
saved for, even when --url names another:
fuobe eval run --suite selftest --engine demo # a free self-test of the harness
fuobe eval run --suite soul --engine open --looks v1-general --variants recipe,prompt-only
fuobe eval compare latest~1 latest --fail-on clip --threshold 1 # exit 1 on a regression
fuobe eval trash latest # the run's generations to that Fuobe's Trash
See scripts/eval/README.md for the suites, metrics, blind review and
the promote rule.
fuobe worker
Runs this PC's GPU as a worker for a studio: it takes the studio's ComfyUI jobs over HTTPS and runs them on its own ComfyUI, and it opens no port. See gpu-workers.md.
pnpm install --frozen-lockfile # once, in the checkout: the build's tools
node scripts/build-worker.mjs # then the worker's shared parts
fuobe worker setup # the studio's address, the token, ComfyUI's folder, the model and worker folders, ffmpeg's path
fuobe worker run # until Ctrl+C; exit code 4: another worker runs on the same worker folder
fuobe worker pause # finish the job, then stop its ComfyUI; --now: stop now; --for 2h: back by itself
fuobe worker pause --choose # asks for 1, 2 or 4 hours, then stops now (the Ctrl+Alt+P shortcut)
fuobe worker resume
fuobe worker status
fuobe worker baseline # the desktop's usual share of the GPU, for studio jobs first
fuobe worker install # Windows: shows a sign-in task and pause/resume shortcuts; --yes adds them
Skills for other agents
Fuobe's skills are Agent Skills, so the open skills CLI
installs them into Claude Code, Codex, Cursor, OpenCode, Copilot and others:
npx skills add workingprototype/Fuobe --skill fuobe # how to drive Fuobe (MCP first, then this CLI)
npx skills add workingprototype/Fuobe --list # the 20 playbooks (UGC videos, product photos, dubs…)
npx skills add workingprototype/Fuobe -a claude-code # all of them, for Claude Code
fuobe lives in .agents/skills/fuobe/; the playbooks in skills/ (see skills/README.md). Each
playbook ends with "Using Fuobe from an agent", naming the MCP tools to call, so connect the MCP
server too (fuobe mcp).
Exit codes and environment
| code | means |
|---|---|
| 0 | done |
| 1 | failed: a generation failed or was canceled, or the server refused the request |
| 2 | the command was mistyped (the message says what to type instead) |
| 3 | still running when --timeout ran out (fuobe wait <id> picks it up again) |
| 130 | stopped waiting with Ctrl+C (the job keeps running) |
| variable | |
|---|---|
FUOBE_URL, FUOBE_TOKEN |
the server and the API token |
FUOBE_CONFIG |
another config file than ~/.config/fuobe/config.json |
FUOBE_DEBUG=1 |
print the stack of an unexpected error |
When something goes wrong
- "Can't reach Fuobe at http://localhost:3000 (connection refused). Is the server running?" —
start it (
pnpm dev, orpnpm build && pnpm start) or pointFUOBE_URL/fuobe loginat it. - "… has a password, so the CLI needs an API token" — create one in Settings → Security → API
tokens, then
fuobe login(or setFUOBE_TOKEN). - "… refused the API token" — it was revoked, or belongs to another server: create a new one.
- "The token "fuobe login" saved is for …, so it isn't sent here" —
--urlorFUOBE_URLnames another server than the one you signed in to: pass--token, orfuobe login --url <that server>. - "(demo)" results — Settings → Placeholder results is on (for a tour): turn it off, and add a key in Settings (cloud), or start ComfyUI (open source). Demo results cost nothing and are labelled in the Library.
- "(not set up)" in
fuobe models, or "Connect … in Settings to run this model" — the model's provider isn't set up yet. - "… is a cloud model, but you asked for --engine open" — pick a model of that engine
(
fuobe models --engine open) or leave out--engine.
What it calls
For script writers who'd rather call the API directly: GET /api/models (kind, engine, op,
q, hidden=1; it answers with the studios' defaults per engine, demoMode, and per model
connected and runs), POST /api/generations (with ?preview=1 to price; a model id Fuobe has
retired runs on the model that replaced it, and the answer gives that modelId with notes saying so;
a script can say what made the run with source (batch, drill, example or test) and sourceName (its own
name, up to 80 characters); a run sent with an API token and no source reads as api, through any route that makes one (the studios'
and apps' routes too), and the admin runs list tells
all of them apart from hands-on runs made on the site),
GET /api/generations[/<id>],
POST /api/generations/<id>/cancel, POST /api/uploads (multipart file), GET /api/files/…,
GET /api/status, GET|PATCH /api/assist/skills[/<name>], POST /api/assist/skills/upload
(?replace=1), a skill's GET …/recipe, POST …/estimate, …/run and …/verify ({level: "plan"})
and GET …/download?format=zip under /api/assist/skills/<name> (estimate and run take values, or
csv, and engine), and POST /api/mcp (JSON-RPC). Every call carries Authorization: Bearer <token>
when there is one, and only to the Fuobe server (never to a link elsewhere, and the saved token only
to the server it was saved for).