Craft CLI

Sync Craft projects with a local folder: clone a world, edit it with your editor or any coding agent, and push the changes back — git-style, with three-way sync and conflict handling.

npm install -g @craftrpgs/cli
craft login
craft systems                                # browse published game systems
craft create "My World" --system "Ashes RPG" # build on one (--blank starts from scratch)
cd my-world
# edit files, then:
craft status
craft push -m "first pass at the heroes"

What you get locally

A cloned project is a plain folder of files: markdown with frontmatter for notes and JSON for typed records (aragorn.character.json), organized in real directories that mirror the project's folders. .craft/ holds the sync state — leave it alone. AGENTS.md / CLAUDE.md and matching skills under .agents/skills/ / .claude/skills/ are included so Codex and Claude Code know how to work with the project the moment you open it.

Commands

| Command | What it does | |---|---| | craft login / logout | Browser sign-in (credentials stored per server) | | craft create <name> | Create a new project and clone it (--system <id\|name> builds on a published system; --blank starts from scratch) | | craft clone <idOrUrl> | Download a project as a local workspace | | craft projects | List projects your account owns | | craft systems [query] | Browse published game systems to build on (featured + community) | | craft status / diff | Show local changes (add --remote for drift) | | craft check | Validate the workspace locally (the same checks the server runs at push) | | craft project-completeness | Worldbuilding completeness report (recommendations; always exits 0) | | craft pull | Apply remote changes; conflicts become sidecar files | | craft push [path ...] -m "..." | Send local changes as one transactional batch (optional pathspecs — file paths or directory prefixes — scope it) | | craft log <path> | A file's version history | | craft publish -m "..." | Snapshot the server state as a numbered release | | craft mv <from> <to> | Rename/move a file, keeping its identity | | craft type new <Name> | Author a new file type locally | | craft image generate/upload | Generate (including local or workspace reference images; opt-in in Settings) or upload images | | craft image expressions/cutouts | Preflight and persist character expression or cutout assets | | craft env [name] | Show or pin the environment for a directory |

Every command takes --json for machine-readable output. Auth is via craft login (browser OAuth); credentials are stored locally and refreshed automatically.

Run craft help <command> for details on any of them.

Environments

The CLI talks to production (craftrpgs.com) by default. craft env <name-or-url> pins the current directory tree to another server via a one-line .craft-env file — handy for keeping a testing folder pointed at a dev server while the rest of your machine uses production. --remote and CRAFT_REMOTE accept an environment name or any origin URL. A cloned workspace always syncs with the server it was cloned from. (Craft developers: set CRAFT_DEV=1 to enable the internal local and staging environment names.)

Requirements

Node.js 20 or newer.