Installing the Craft CLI

Install craft, sign in, and pull a project down to your machine. If you have never used a command line before, start at the top — the steps below assume nothing.

Install Node.js

The CLI runs on Node.js, so that goes on first. Download the LTS installer from nodejs.org, open it, and accept the defaults. It works the same on macOS and Windows, and no command line is involved.

Already have Node? Check the version — anything below 20 needs an update:

node --version

Open your terminal

Every command on this page is typed into a terminal window, one line at a time, pressing Return after each.

You will get a window with a blinking cursor. Nothing here can break your computer — every command below only touches Craft projects and the CLI itself.

Install the CLI

npm install -g @craftrpgs/cli

Confirm it landed:

craft --version

A version number means you are ready.

The install didn't work

"command not found: craft" — the terminal was open before Node was installed, so it hasn't picked up the new command yet. Close the window, open a new one, and run craft --version again.

"command not found: npm" — Node didn't install, or installed somewhere the terminal can't see. Run node --version to confirm, and re-run the installer from nodejs.org if it comes back empty.

A wall of permission errors — npm is trying to write to a folder your account doesn't own. On macOS, avoid sudo npm install; install Node with the official installer (not Homebrew's system Node) and try again.

Sign in

craft login

This opens your browser to sign in; credentials are stored locally on your machine and refreshed automatically. Auth is OAuth-only — there are no pasteable personal access tokens. Any Craft account can use the CLI.

Your first sync

List the projects you own and copy the id of the one you want:

craft projects

Download it — a project URL from the app works in place of the id:

craft clone <projectId>

Move into the folder the clone just created:

cd <project-folder>

The project is now files in folders. Markdown file types are plain markdown with YAML frontmatter; typed records are JSON files named like Aragorn.character.json, in real directories that mirror the project's folders. The clone also includes the .craft/ folder (sync state — leave it alone) and generated AGENTS.md/CLAUDE.md instructions, so a coding agent opened in the folder immediately knows how to work with the project.

Edit whatever you like with any editor, then see what changed:

craft status

Send it back:

craft push -m "message"

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.

Next

• Use With Coding Agents — hand the editing to Claude Code, Codex, or another agent.
• Command Reference — every command, grouped by task.