Calliope

Calliope CLI 创作桥

The CLI is the only way content enters a Calliope project from outside the web UI. It writes finished text: beats, cast, scenes, clips, continuity requirements, and the source novel itself. It never calls a model, never touches images or video, and never deletes anything.

The one rule

Read → hash → write → verify. Every time, for every group.

The user edits in the web UI while you work. A write built on a read from ten minutes ago silently overwrites their edit. So:

calliope-cli project hash --project 7 --json      # fingerprints, right now
calliope-cli story list --project 7 --json        # the content you are acting on
calliope-cli story append --project 7 --file b.json \
    --expect-hash <the story_beats value from step 1>

--expect-hash is what makes this safe. It is compared inside the write transaction, so nothing can slip in between the check and the write. Skip it only for project create.

Find the project

calliope-cli project list --json          # id, title, status, counts
calliope-cli project show --project 7 --json

--json and --dry-run go at the end of the line, as above. They are also accepted in front of the command path — calliope-cli --json project list gives identical output. Prefer the trailing form; it reads as one command.

project show returns counts and the plan state. The source text is not included — add --with-idea when you need it, because a novel is 34k+ chars and plan next summaries must stay readable.

Read the source text

The long-form novel lives in projects.idea. Do not load all of it:

calliope-cli project source --project 7 --from-chars 0 --to-chars 8000 --json
calliope-cli project source --project 7 --grep "老陈" --context-lines 4 --json

Both return an object, not a bare string: {text, chars, lines, is_long, from_chars, to_chars, truncated}, or {chars, lines, is_long, matches} for --grep. chars is the size of the whole text even when you read a window, and is_long is true past 2000 characters. Each --grep hit carries line, context_before, context_after, and the list is capped at 200 — re-grep with a narrower needle rather than trying to page it.

Slice by character offset or grep, repeatedly, until you have what you need. Then close the loop with context set requirements.

Writing a novel in? Use a file, always:

calliope-cli project set --project 7 --idea-file novel.txt

Never pass a multi-line novel to --idea. calliope-cli.bat goes through cmd.exe, and %* re-expansion treats a raw newline as the end of the command line — everything after it is dropped, exit code still 0. You would write a truncated novel and lose the rest of your flags with no error. --idea is only safe for a single line. (--idea-file - reads stdin, which is also fine.) Giving both --idea and --idea-file is exit 2: they name the same column.

ingest_mode is set once, at project create --ingest-mode external. It is not editable afterwards — check project show rather than trying to change it.

What to write next

Do not decide this yourself. The CLI knows the ordering and why:

calliope-cli plan next --project 7 --json

{
  "project_id": 7,
  "step": "cast.upsert",
  "why": "beats exist but no cast; scenes reference characters by name",
  "counts": {"story_beats": 24, "characters": 0, "scenes": 0, "clips": 0},
  "plan_state": "missing",
  "basis_hash": "…",
  "hint": "calliope-cli schema show cast upsert"
}

step is one of:

clips.append and context.set also return targets (the scene ids still to shoot). Any step may return a note — anything true but not a reason to stop what you were doing. plan next never gates on a note; it also uses one to report a gapped or duplicated beat sequence (story order has the detail). When several notes apply they are joined with " | ".

The order is beats → cast → script → clips → continuity, and it is not negotiable: a scene names characters by name, and a continuity ledger describes shots that must already exist.

Payload shapes

Never guess a field name. schema show is generated from the same Pydantic models the validator uses, so it cannot drift:

calliope-cli schema show                       # every group/verb
calliope-cli schema show story                 # the verbs in one group
calliope-cli schema show story append          # {group, verb, accepts, payload, schema}
calliope-cli schema validate --group story --verb append --file b.json

The inner schema is the JSON Schema; payload says whether the file is an array or an object. Where a field takes a closed set of keys rather than free strings — context set's ledger buckets — schema carries it as propertyNames.enum and x-allowed-keys, matching what the validator enforces. An unknown group or verb is exit 4, not an empty object.

schema validate checks a payload without writing. Use it before any batch you are unsure about — it costs one process and catches every field mistake at once.

Compact reference (* = required):

story append / replace-range  -> [array]   title*, description, order_index
story update                   -> flags    --beat-id --title --description --order-index
cast upsert                    -> [array]  name*, kind(character|location|item), role, age,
                                          appearance, personality, description, reference_image_path
cast update                    -> flags    --entity-id --kind --role --age --appearance
                                          --personality --description
                                          --reference-image-path
                                          --portrait-path --sheet-path --consistency-prompt
                                          (last three: clear a stale ref with "" only)
script append / replace-range  -> [array]  heading, action, dialog, duration_sec,
                                          order_index, location_id, characters[]
script update                   -> flags    --scene-id --heading --action --dialog
                                          --duration-sec --order-index --location-id
clips append / replace-range   -> [array]  description, shot_size, duration_sec,
                                          order_index, dialog_lines_covered[]
clips update                    -> flags    --clip-id --description --shot-size
                                          --duration-sec --order-index --dialog-lines-covered
context set                    -> [object] overview{}, requirements{}
project set                    -> flags    --title --idea --idea-file --genre --tone
                                          --target-duration --status --cover-path

update verbs take flags, not a payload file. The others take --file, and --file - reads stdin if you already hold the JSON.

• What a write returns: story append → beat_ids, script append → scene_ids, clips append → clip_ids, cast upsert → results, one {id, name, kind, action} per entry where action is created / updated / unchanged. Only cast upsert tells you whether anything actually changed, because it is the only one that is an upsert by name.
• --dialog-lines-covered is comma-separated: --dialog-lines-covered 1,3,7.
• --entity-id is a row id or the exact name. Renaming is not supported — name is the upsert identity, and changing it would orphan the scene's references to that character.
• cast list comes back grouped by table — {"characters": [...], "locations": [...], "items": [...]} — and each row carries its own kind. script list does not include a scene's characters; read one scene with script get --scene-id N, which nests its clips under clips.
• --portrait-path / --sheet-path / --consistency-prompt point at images the user generated in the web UI. The CLI has no renderer and will not invent them; the only accepted value is "", to clear a stale reference.
• script update cannot change which characters are in a scene. characters is settable only when the scene is created — use script replace-range on that scene if the cast actually changed.

shot_size is a closed list, exact spelling

wide · medium · closeUp · insert · overShoulder

closeup is rejected, not normalised. The CLI does not guess which of two camelCase spellings you meant, because a whitelist that later gains a value differing only by case would make the guess silently wrong. "" is the one accepted empty form — it means "unset".

Fields you cannot write

clip_path, workflow_id, video_settings_json, chain_from_prev, video_node_id, render_status, portrait_path (from a payload), and every bookkeeping column a payload has no business naming — id, project_id, created_at, scene_id — are rejected with exit 2. Those belong to the render pipeline or to the CLI's own addressing. If you need one changed, the user does it in the web UI.

order_index is the awkward one: schema show lists it for every group, but only beats honour it. Scenes and clips take it and overwrite it with a dense append order. See the two sections below before sending one.

If another skill did the novel conversion

The common shape of this work: some third-party skill turns the novel into an intermediate artifact, and you then write that into Calliope. Fully supported. One rule covers it:

The intermediate artifact's shape is your problem. Calliope's shape belongs to schema.

That skill may emit markdown, its own JSON, prose — anything. The CLI has never heard of its format and will not try to. Ask the CLI for the shape, then convert in your own context:

# 1. ask what the shape is -- never infer it from the upstream output,
#    and never reverse-engineer it from what `get` happens to return
calliope-cli schema show story replace-range
calliope-cli schema validate --group story --verb replace-range --file beats.json

# 2. fingerprint the rows you are about to overwrite
calliope-cli project hash --project 7 --json

# 3. dry-run first: it prints both sides plus the invariant preflight
calliope-cli story replace-range --project 7 --from-index 1 --to-index 999 \
    --file beats.json --expect-hash <story_beats hash> --dry-run

# 4. same line without --dry-run

Do not hand the upstream artifact to --file unchanged. Four habits it reliably has are all caught, and catching them is the design working, not an obstacle to route around:

So when a write comes back exit 2, fix the conversion, not the CLI. There is no flag to loosen validation and there will not be one: a payload that reached the database half-converted would look like a success that silently did nothing.

One upstream habit gets through, so watch it yourself: order_index. It is listed in schema show for every group, so an artifact that carries positions looks perfectly valid — and the three groups then disagree about what it means:

An upstream artifact numbered 1, 3, 7 therefore becomes three beats at 1, 3, 7 with holes 2, 4, 5, 6 — not a rejection, and not what a dense list would have been. After writing beats, run story order --project 7 --json and read the holes and duplicates. For scenes and clips the safest move is to strip order_index from the artifact during conversion and let append order speak.

Compatibility is a property of the CLI boundary, not of this skill. Whatever the upstream produced — valid, nearly valid, or prose — either it validates or it never enters the database.

Do not route [CARRY] constraints through the third-party skill. It rewrites descriptions, reorders, and "improves" copy; constraint lines do not survive that. Append them after conversion, or accept that upstream has no idea the constraint exists.

One thing the CLI being used instead of the built-in generators means: those generators refuse a source text over 2,000 characters (exit 422), because they would spend a real call on text they cannot use and return beats that quietly ignore it. Nothing here refuses — writing a novel's worth of beats is the point.