# 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:

```text
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

```bash
npm install -g makefx
makefx login
makefx spaces create "My Game" --init
makefx models list --available
```

## Generate

Generate creates a new Asset:

```bash
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:

```bash
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:

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

Choose a completed result explicitly:

```bash
makefx variants activate <variant-ref>
```

See [comparing and selecting Variants](/docs/ai-media-variants) for the human
decision behind these actions, and [tracking the creative record](/docs/reproducible-ai-media)
for how Recipes, References, and Lineage fit together.

## Files and organization

```bash
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:

```bash
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:

```bash
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:

```text
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:

```bash
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

```bash
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.