craft-cli

Agent-friendly CLI for controlling Craft through the official Craft API.

Project task tracking and future-work planning live in Linear, not in repo docs. Use the craft-cli Linear project and vNext backlog parent MAR-1188 as the source of truth for backlog state.

Requirements

• Node 24.x
• A Craft API base URL from Craft Imagine > API

The repo includes .nvmrc, so compatible Node version managers should select Node 24 automatically.

Development

npm install
npm run build
npm run dev -- --help

Release automation uses Changesets:

npm run changeset
npm run pack:dry-run

Configuration

The CLI supports both .env and named local profiles. Flags override .env; .env overrides the selected profile.

The fastest local setup is .env. The CLI automatically loads .env from the current working directory before oclif parses flags:

cp .env.example .env

Then edit .env:

CRAFT_API_BASE_URL=https://connect.craft.do/links/.../api/v1
CRAFT_API_TOKEN=optional-token

CRAFT_API_TOKEN is optional because some Craft connection URLs may already carry the access context. .env is gitignored.

For reusable local profiles:

./bin/run.js profiles add default --base-url https://connect.craft.do/links/.../api/v1 --token <token>
./bin/run.js profiles list --json
./bin/run.js profiles show default --json
./bin/run.js doctor --profile default --json

Profiles are stored in the OS config directory:

• macOS/Linux default: ~/.config/craft-cli/profiles.json
• Windows default: %APPDATA%/craft-cli/profiles.json

Override with CRAFT_CLI_CONFIG_DIR for tests or isolated runs.

Commands

craft-cli doctor
craft-cli profiles list --json
craft-cli profiles add default --base-url https://connect.craft.do/links/.../api/v1
craft-cli profiles show default --json
craft-cli profiles remove default --confirm
craft-cli folders list --flat --json
craft-cli documents list --location unsorted --json
craft-cli documents list --folder <folderId> --fetch-metadata --json
craft-cli documents list --all --limit 20 --json
craft-cli documents get <documentId> --json
craft-cli documents create --title "Meeting notes" --markdown "# Notes" --dry-run --json
craft-cli documents move <documentId> --folder <folderId> --dry-run --json
craft-cli documents delete <documentId> --dry-run --json
craft-cli blocks get <documentId> --format markdown
craft-cli blocks insert --page <documentId> --markdown "New paragraph" --position end --dry-run --json
craft-cli blocks update <blockId> --markdown "Updated paragraph" --dry-run --json
craft-cli blocks move <blockId> --after <siblingId> --dry-run --json
craft-cli blocks delete <blockId> --dry-run --json
craft-cli daily-notes get --date today --max-depth 0 --json
craft-cli daily-notes get --date 2026-05-06 --format markdown --output daily-note.md
craft-cli search documents "project alpha" --limit 10 --json
craft-cli search blocks "project alpha" --document <documentId> --before 3 --after 3 --json
craft-cli tasks list --scope active --limit 20 --json
craft-cli tasks list --scope document --document <documentId> --json
craft-cli tasks add --content "Follow up" --inbox --dry-run --json
craft-cli tasks add --content "Prep notes" --document <documentId> --dry-run --json
craft-cli tasks update <taskId> --state done --dry-run --json
craft-cli tasks move <taskId> --daily-note today --dry-run --json
craft-cli tasks complete <taskId> --dry-run --json
craft-cli tasks delete <taskId> --dry-run --json
craft-cli folders create --title "Projects" --dry-run --json
craft-cli folders move <folderId> --root --dry-run --json
craft-cli folders rename <folderId> --title "Road to 90kg" --dry-run --json
craft-cli folders delete <folderId> --dry-run --json
craft-cli collections list --limit 20 --json
craft-cli collections list --document <documentId> --json
craft-cli collections schema <collectionId> --format json-schema-items --json
craft-cli collections items <collectionId> --max-depth 0 --json
craft-cli collections items add <collectionId> --item-json '{"title":"Build CLI"}' --dry-run --json
craft-cli collections items update <collectionId> <itemId> --patch-json '{"title":"Updated"}' --dry-run --json
craft-cli collections items delete <collectionId> <itemId> --dry-run --json
craft-cli upload file ./notes.md --page <documentId> --experimental --dry-run --json
craft-cli comments add --comment-json '{"blockId":"<blockId>","text":"Review this"}' --experimental --dry-run --json
craft-cli api coverage --json
craft-cli api endpoints --status deferred --json
craft-cli docs generate --output docs/commands.md --json
craft-cli docs agent-playbook

Write commands use the shared dry-run/confirm/force safety layer. Start with --dry-run --json; non-destructive writes require --confirm, and destructive deletes require --confirm --force. Commands backed by Craft endpoints documented as experimental also require --experimental.

Mutation safety rules are documented in docs/safety.md. Test harness rules are documented in docs/testing.md. Release automation is documented in docs/release.md.

For practical workflow examples, see docs/workflows.md.

For AI-agent usage examples, see docs/agent-playbook.md or run:

./bin/run.js docs agent-playbook

For generated command metadata, see docs/commands.md or regenerate it with:

./bin/run.js docs generate --output docs/commands.md

Live tests are opt-in and skip by default:

npm run test:live

Release Setup

This repo is wired for the Changesets release-bot flow:

1. Feature work includes a .changeset/*.md file from npm run changeset.
2. Merging to master opens or updates the Changesets version pull request.
3. Merging that version pull request publishes to npm through GitHub Actions.

The package is configured to publish as @mrck-labs/craft-cli because the unscoped craft-cli name is already registered on npm. The binary remains craft-cli.

Manual repository setup before the first release:

1. Add a GitHub Actions secret named NPM_TOKEN with npm publish rights for @mrck-labs/*, or configure npm trusted publishing for .github/workflows/release.yml.
2. In GitHub Actions settings, allow workflow read/write permissions and allow GitHub Actions to create pull requests.