CLI Reference

The CLI operates on the same Spaces, Assets, Variants, Recipes, References, Lineage, 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

npm install -g makefx
makefx login
makefx spaces create "My Game" --init
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

Regenerate, Retry, and Activate

Regenerate a completed Variant when the result should be different:

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

The successful sibling becomes main by default. Pass --no-activate when the current selection should remain unchanged.

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>

See comparing and selecting Variants for the human decision behind these actions, and tracking the creative record for how Recipes, References, and Lineage fit together.

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>

MCP cannot read caller-local paths, so upload and filesystem output belong in the CLI.

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