CLI Command Reference

Every craft command, grouped by task. All commands take --json for machine-readable output. For installation and your first sync, start with Install.

Signing in and out

craft login

Signs in with your browser and stores credentials locally, refreshing them automatically from then on. The full walkthrough is on the Install page.

craft logout

Signs out and forgets the credentials stored on this machine.

Get a project onto your machine

craft projects

Lists the projects you own, with their ids.

craft clone <projectId>

Downloads a project into a folder named after it. A full project URL from the app works in place of the id, and an optional directory argument clones somewhere specific — pass . to use the current directory (a folder you already made, with git init run or dotfiles in it, is fine).

craft systems

Browses published game systems — projects that ship file types, rules content, and GM instructions as a starting point. This lists the featured row and the community catalog; search with craft systems <query> and narrow with --tag. --community skips the featured row, and long listings page with --limit and --cursor (each page prints the cursor for the next one).

craft create "My World" --system "Ashes RPG"

Starts a new project on a published system, cloning your pick as its base.

craft create "My World" --blank

Starts with an empty project instead — no file types, no content — so you can author your own types with craft type new. Run craft create with neither flag in a terminal and it offers the featured systems as an interactive picker.

craft create . --blank

Creates the project right here, named after the current folder. An optional directory argument works like clone's, as in craft create "My World" my-dir --blank. On any of these forms, --description "..." sets the project description, and --empty is an older alias for --blank.

The edit loop

craft status

Shows what changed locally. Add --remote to see server drift too. With --json the output lists changed entries only — --full expands it to every tracked file plus the sync ledger.

craft diff

Shows the actual content changes — the whole workspace, or one file when you pass its path.

craft pull

Brings down remote changes. If someone edited the same file in the app while you edited it locally, pull saves the server version next to yours as a .remote.* sidecar file. Compare the two, then run craft resolve <path> to keep your version or craft checkout <path> to take the server's.

craft push -m "message"

Sends your changes as one transactional batch. Pushes are all-or-nothing by default: if any file fails validation, the whole batch is rejected with exact field errors, and nothing on the server changes. --dry-run shows the operation list without sending anything, and --partial applies what it can instead of rejecting the whole batch. One push carries at most 500 operations; a bigger change set must go in smaller pushes, since --partial does not split it for you.

craft push Handbook -m "message"

Path arguments scope the push. Each one is a file path or a directory prefix — Handbook means everything under /Handbook — and only matching changes are sent; a path that matches no pending change is an error, so a typo can't push the wrong thing. Scoped pushes can't carry --include-types — type changes have no path, so push types in a separate, unscoped push. And when a pull left a file conflicted, craft push --force <path> makes your version win it.

craft mv <from> <to>

Renames or moves a file. It keeps the file's identity, so its history and every reference to it survive the move.

History and releases

craft log <path>

A file's version history, with the push messages attached. Shows the newest 20 versions; raise that with --limit (up to 100).

craft publish -m "notes"

Snapshots the whole project as a numbered release. Pushes version individual files; publish checkpoints everything at once, and --name "..." titles the release. Releases are private unless you pass --public, which also makes the project visible on the discover page.

craft releases

Lists the project's releases.

Import a CDF

craft import world-backup.zip --dry-run

Previews the plan for landing a Workspace CDF zip — the same preview-first plan as the app's import panel. Drop --dry-run to apply it as one batch.

Files match by referenceId, and an import never deletes or moves yours. Files that changed on both sides since the fork are conflicts — listed and left untouched unless you pass --overwrite (their version wins; yours stays in version history). File type changes from the zip apply only with --include-types, and project settings changes only with --include-settings. To veto parts of the plan, pass --exclude <referenceId> for individual files or --exclude-setting <key> for a single settings change — the ids and keys come from a --dry-run --json plan. -m attaches a message to the resulting versions, and --project <id> targets a project from outside its workspace.

craft import Goblin.monster.json

A single CDF file works too. A clone is already a Workspace CDF on disk, so exporting is just zipping the folder, or use the app's export button. See CDF Import & Export.

New file types

craft type new Faction

Scaffolds a file type at .craft/file-types/faction.json. Edit its schema, then create files named like <Anything>.faction.json. Pass --markdown for a markdown type with no schema. --designation marks the type as one of the platform concepts (character, location, gm_instructions, or game_start) — most types need none — and --category sorts it into a group (world, game_master, or game_system).

craft push --include-types

Pushes the new type and its files together.

Images

craft image generate --prompt "a windswept coastal fortress"

Generates an image and prints an image object you can paste into any file's image field and push.

craft image generate --prompt "the same hero in royal armor" --ref hero-sketch.png

Guides a generation with a local image, which Craft uploads to your project first. You can repeat --ref up to three times, and you can also point it at a tracked workspace file to use that file's current image.

Stored art-style instructions are composed into the prompt automatically, so write subject-only prompts. --for <path> applies the named file's type-level style instructions instead of the project's, and --no-style sends the prompt verbatim. --model and --size override the project's default image model and size.

craft image upload cover-art.png

Uploads an existing image and prints the same kind of image object. Uploads are always available (re-encoded server-side and rate-limited).

craft image expressions "Heroes/Aragorn.character.json"

Generates a character's expression images — the per-mood portraits behind Character Expressions — and saves them onto the pushed file (run craft pull afterward to see the result locally). Without --yes it only prints the plan and the estimated cost; nothing is charged. --missing-only keeps assets that already exist, --only <name> targets specific expressions (repeatable), --with-cutouts also produces the transparent cutouts, and --credits spends purchased credits.

craft image cutouts "Heroes/Aragorn.character.json" --portrait

Generates transparent full-figure cutouts — what visual novel mode uses to put characters in the scene — from art that already exists: the portrait with --portrait, or every expression with --expressions (pick exactly one). Takes the same --missing-only, --credits, and --yes flags as expressions, and --only works with --expressions.

Turning on image generation

Generating images through the CLI spends your energy, so it is off by default — a script or agent can never spend on your behalf until you allow it. To turn it on, open Settings → Account in the Craft app, find the Image generation for the Craft CLI card, and enable Allow image generation. Until you do, image generation commands fail with an error pointing at this setting.

Generation always uses daily energy unless you also enable Allow credit spending on the same card, which lets the CLI spend purchased credits when a command explicitly passes --credits. Uploading an existing image never requires either setting.

Voices

craft voices

Lists the text-to-speech voice catalog, ids plus traits, so you can assign voices without guessing. Set a character file's optional voice field to an id from this list — the field is covered in File Types — and the Game Master's voice at settings.gm.voiceId in .craft/project.json. Narrow the list with the --language, --gender, and --age filters; language takes the catalog code, like en or multilingual.

Maps and playability metadata

Maps, game start configuration, GM instruction triggers, and playable flags are app-managed metadata: they never appear in the working tree, so these commands read and write the server directly, and the target file must be pushed first.

craft map get "Places/Old Town.location.json"

Prints the interactive map stored on a location file, with element links rendered as workspace paths.

craft map set "Places/Old Town.location.json" --file map.json

Replaces the whole map, so the loop is get, edit, set. The authoring JSON is the stored map shape with conveniences: areas and points may carry a link (a workspace path, slug.type token, or referenceId) instead of a raw file reference, and element ids are minted when omitted. The background image must be Craft-hosted — generate or upload one with the image commands and paste its url. A clone ships the full format at .craft/instructions/authoring-maps.md.

craft meta get <path>

Shows a file's designation metadata: its game start configuration, GM trigger, playable flag, and a map summary.

craft meta set-game-start "Openings/Prologue.game_start.json" --file start.json

Configures a game start: the starting location, the characters players can pick, and the opening — a scripted first message or a prompt the GM improvises from. The JSON names locations and characters by workspace path (they must be pushed).

craft meta set-gm-trigger "Rules/On Combat.gm_instructions.md" --file trigger.json

Turns a GM instruction file into a triggered rule that fires on narrative phases or on tool events like character updates. --clear removes the trigger, making it a normal instruction file again.

craft meta set-playable "Heroes/Aragorn.character.json" true

Marks a character as playable, so game starts can offer it as a pick.

Check your work

craft check

Runs a deterministic, local-only validation of the workspace — the same checks the server runs when a push lands: every JSON file against its type schema, file type schemas and expressions, references, layouts, and project settings. It also warns if stored content still carries values under computed expression fields (push strips those silently). Run it after schema or content edits; failures are push rejections waiting to happen.

craft project-completeness

Reports how complete the project is against the worldbuilding quality bar — cover image, root map, cross-links, image coverage, descriptions, and so on. Everything it reports is a recommendation (a text-only project can ignore the image warnings on purpose), so it always exits 0. Run it before calling worldbuilding work done.

For authoring computed fields from a clone, see Computed Fields.