CLI Reference

The CLI operates on the same Spaces, Assets, Variants, Recipes, References, Collections, Drafts, Bindings, canvas organization, and permissions as the web app. Use it for terminal automation and caller-local file upload or download.

Commands follow noun verb. Assets and Variants use compact references:

asset:name~prefix
asset:name~prefix@variant

Run makefx --help or makefx <noun> --help for the authoritative commands, flags, model choices, and output options.

Start

Install the canonical makefx package on npm:

npm install -g makefx
makefx login
makefx spaces create "My Game" --init
makefx spaces current --json
makefx models list --available

Generate

Generate creates a new Asset:

makefx image generate "A painted market" \
  --name "Market" --type scene -o market.png

makefx video generate "A slow push through the market" \
  --name "Market Push" --type animation -o market.mp4

makefx audio music generate "Warm acoustic theme" \
  --model eleven-music --name "Theme" -o theme.mp3

History and continuation

Inspect typed parents and descendants, or continue one exact Variant:

makefx variants history <variant-ref>
makefx image derive "Same character, winter clothes" \
  --refs <variant-ref> --name "Winter hero" --type character -o winter.png
makefx variants fork <variant-ref> --name "Hero branch" \
  --changes "Keep everything; make the expression slightly happier" --wait
makefx variants copy <variant-ref> --name "Hero copy" --type character

Derive creates a Recipe from exact inputs. Fork edits a restored Recipe and runs it into a new Asset. Copy duplicates exact media without a provider. Generate accepts no inputs. Upload local files before deriving.

Regenerate, Vary, Retry, and Activate

Regenerate a completed Variant to replay its Recipe unchanged:

makefx image regenerate <variant-ref> --wait

Vary when the sibling should be subtly different:

makefx image vary <variant-ref> "Warmer light" --wait

Both add a sibling Variant to the same Asset. Vary patches the restored Recipe; Regenerate does not. The result becomes main by default; use --no-activate to keep the current one.

Retry only a failed Variant whose Recipe must stay unchanged:

makefx variants retry <variant-ref>
makefx variants show <variant-ref> --wait

Choose a completed result explicitly:

makefx variants activate <variant-ref>

Files and organization

makefx assets upload hero.png --name "Hero" --type character
makefx assets download <variant-ref> -o hero.png
makefx collections add <collection-id> <asset-ref>

Plan a Draft chain

Drafts plan generation without running it. Create Drafts, then bind one output to another Draft's input:

makefx drafts create "Character" --media image \
  --generator image/pro \
  --recipe '{"operation":"generate","assetType":"character","prompt":"Paint the character"}' \
  --destination new_asset
makefx drafts create "Character Motion" --media video \
  --generator video/seedance-2-frame \
  --recipe '{"operation":"generate","assetType":"animation","prompt":"Animate the character walking into frame"}' \
  --destination new_asset

makefx bindings set <character-motion-draft-ref> start_frame_variant_ref \
  --source draft-output --ref <character-draft-ref>
makefx collections pin <review-collection-id> --x 240 --y 120
makefx spaces lens type

Reuse a completed Variant's Recipe and exact-Variant references:

makefx drafts create --from <variant-ref> --name "Next hero pass"

It creates a new Asset by default; --destination sibling targets the source.

Run an approved workflow

An agent can plan a speech Draft, bind its output into an alignment Draft, and bind the aligned result into a video Draft. It then requests one human checkpoint through MCP:

graph_run({
  space_id: "<space-id>",
  draft_refs: ["<speech-draft-ref>", "<alignment-draft-ref>", "<video-draft-ref>"],
  request_id: "dialogue-scene-07",
  include_upstream: true,
  require_approval: true
})

The canvas shows the pending graph-run summary. Approving it runs the exact request in dependency order; rejecting it starts no generation. The agent polls graph_run_status with the compact run reference after approval. Each completed Draft produces an ordinary Variant with its resolved References, Recipe and ordered Reference receipt.

The equivalent CLI workflow is:

makefx drafts run <speech-draft-ref>
makefx graph run <alignment-draft-ref> <video-draft-ref> --upstream --wait
makefx graph status <graph-run-ref> --json

Permanent deletion

makefx variants delete <variant-ref> --yes
makefx assets delete <asset-ref> --yes
makefx spaces delete <space-id> --yes

There is no trash. Activate another Variant before deleting the current one; delete the Asset to remove its only Variant.

Automation

Prefer --json where help advertises it. Persist returned compact references, read accepted Variants until terminal, and do not repeat media creation merely because a local wait ended.