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.

craft env alpha

For alpha testers: pins the current folder, and everything under it, to Craft's alpha environment (alpha.craftrpgs.com) instead of production. Run craft login there to sign in on alpha. craft env with no argument shows which environment the folder uses, and craft env --clear goes back to production. A pasted alpha project URL clones from alpha in any folder, and craft login and craft logout take --remote production or --remote alpha to pick one explicitly.

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, and Craft's default GM Instructions — 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, or game_start) — most types need none.

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 the game screen uses to stand 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, linked locations, transports, game start configuration 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.

An area or point can also carry an exit, which makes it a way to another location (a door, stairs, a gate, a portal). Its to takes a workspace path like link does; leave to out for the way out to the location whose map this map sits on. See Exits and Linked Locations.

craft meta get <path>

Shows a file's designation metadata: its game start configuration, playable flag, and a map summary. On a location it also shows its transport, its map exits, and every linked location, read from both ends.

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

Configures a game start. The JSON names locations and characters by workspace path (they must be pushed):

• startingLocation and startingCharacters: where play begins and the characters players can pick.
• opening: how the first turn opens. A static opening is a scripted first message, written as lines of narration and dialogue. A dynamic one is a prompt the GM improvises from. Use characterOpenings to give a character their own scripted opening.
• currentState: how the scene stands when the game opens. Its people are who else is there, each with an optional side (ally, enemy or neutral), the map area they're in, and whether they're hidden. purpose is what the opening scene is for, and objectives what the party works toward from the first turn. trackers sets how the world's trackers start, by key, including the time the game opens at (key time).
• gmNotes: private facts the GM reads on its first turn instead of looking them up, such as who the people at the start are and what they want. Players never see them.

A clone ships the full format at .craft/instructions/making-it-playable.md.

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

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

craft meta link "Places/The Ring Kitchens Cellar.location.json" "Places/The Ring Kitchens.location.json" --file link.json
craft meta unlink "Places/The Ring Kitchens Cellar.location.json" "Places/The Ring Kitchens.location.json"

link says how two locations relate without a spot on a map: one part of the other, both parts of one place, or separate places joined by a way (stairs, a road, a portal). It replaces whatever was between them, and saving can move a location into or out of another. unlink removes everything between the two.

craft meta set-transport "Places/The Sea Wyrm.location.json" --file ship.json

Makes a location a transport, such as a ship, caravan or train that people board. Its own map is where people aboard stand. --clear turns it back into an ordinary location. A clone ships the shapes and rules for links and transports at .craft/instructions/linking-locations.md; see also Exits and Linked Locations.

Visual novels

A visual novel is one document owned by its author, separate from the project's files, so it has its own commands and syncs as a single JSON file. Inside a workspace, story files live in .craft/visual-novels/, where a normal craft push never touches them.

craft vn create "Lanterns Over Kestrel Bay"

Starts a story — in the workspace's project, where the whole team sees it, unless you pass --personal — and pulls it straight into a file.

craft vn list
craft vn pull <id>

Lists the project's stories (--mine lists all of yours) and pulls one into a file. Pull won't overwrite edits you haven't pushed unless you pass --force.

craft vn check .craft/visual-novels/lanterns-over-kestrel-bay.vn.json
craft vn push .craft/visual-novels/lanterns-over-kestrel-bay.vn.json

check validates the file locally: the document's shape, field names, and every reference between pages, cast members, expressions, chapters and music. push runs the same checks and saves the file as the story's draft; it refuses when the story changed since you pulled it, such as an edit in the app's editor, so nobody's work is overwritten by accident.

craft vn publish .craft/visual-novels/lanterns-over-kestrel-bay.vn.json --unlisted

Freezes the draft as the version readers get. --unlisted shares it by link, --public also lists it on Discover, and --private takes it down.

craft vn assets <id or file>

Prints the art a story can use — its project's characters with their portraits, cutouts and expressions, its locations as backdrops, and your studio music — ready to paste into the story. A clone ships the full story format at .craft/instructions/authoring-visual-novels.md.

GM Instructions

Your world's GM Instructions, player options and trackers all live in one setting. See The Game Master for what they do in play.

.craft/project.json → settings.gameOptions

Edit it like any other setting and send it with craft push. It holds three things:

• instructions: each has a body and a "when": always, situational or procedure. A situational one also has a trigger that names its moment, such as "When a character drops to 0 HP". A procedure has a name and a trigger that says when to use it, and "pruning": "on-compaction" keeps it in the GM's context until the game's memory is next compacted. A section is optional, and so is a situational instruction's name.
• options: each player option has a key, a label, a kind (one, several or toggle), a default, and choices. Each choice carries the instructions it sends to the GM.
• sections: the headings your instructions are grouped under. A tracker is an instruction with a tracker definition: what it shows and the rules the GM keeps it by.

The same limits apply as in the app, such as 10,000 characters of always-on instructions, 100 situational ones and 25 procedures of the world's own. A clone ships the full format, with an example and Craft's defaults, at .craft/instructions/upgrading-to-gm-harness-2.md.

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), and if your GM Instructions break a limit the app's editor enforces. A push accepts those, but the app won't save an edit to your GM Instructions until they're fixed. 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, game start, GM Instructions, 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.