craft

craft-cli

CLI for the Craft.do workspace API. Read, write, and manage docs from the terminal.

Install

git clone https://github.com/gustin/craft-cli.git
cd craft-cli
mise install
mise trust
npm install

Setup

Create .mise.local.toml with your Craft API credentials:

[env]
CRAFT_API_KEY = "pdk_your-key-here"
CRAFT_API_BASE = "https://connect.craft.do/links/YOUR_LINK/api/v1"

Get these from Craft Settings > API Connections.

Usage

Browse

List folders, search docs, read content.

craft folders
craft recent
craft docs --folder Business
craft docs --sort modified --since today
craft search "ontology"
craft search "TODO|FIXME" --folder Product
craft search "query" --title
craft search "pattern" --doc <docId>
craft read <docId>
craft read <docId> --meta
craft today
craft tasks

Write

Create docs, append content, upload files. Pipe content via stdin.

craft create "title" --folder Product
craft append <docId>
craft update <blockId>
craft upload <docId>
craft mv <docId> Product
craft delete <docId>

Blocks

Operate on individual blocks within a doc.

craft rmblock <blockId>
craft mvblock <blockId> --to <docId>

Collections

Manage structured data in Craft collections.

craft collections
craft collection:schema <colId>
craft collection:items <colId>
craft collection:add <colId> "title"
craft collection:update <colId> <itemId>
craft collection:rm <colId> <itemId>

Folders

Create, move, and remove folders.

craft mkdir "name" --parent Product
craft mvfolder "Old" "New"
craft rmfolder "Temp"

Render

Render mermaid diagrams from .mmd source files to ASCII (local markdown) and SVG (Craft upload).

craft render docs/ontology.mmd --local-only
craft render docs/ontology.mmd --doc <docId>

Source files use %% diagram:NAME markers to delimit diagrams. The corresponding .md file uses <!-- mermaid:NAME --> markers as injection points for rendered ASCII.

Other

craft open <docId>
craft link <docId>
craft help

Piping

Pipe content in via stdin:

echo "# Meeting Notes" | craft create "Weekly Sync" --folder Business
cat docs/ontology.md | craft create "Ontology" --folder Product

Pipe output to Claude CLI:

craft read <docId> | claude "summarize this doc"
craft search "auth" --json | claude "which docs discuss OAuth?"

Flags

All commands accept --json for raw API output. Date filters accept ISO dates (2026-01-28) or relative values (today, yesterday, tomorrow).

Claude Code Plugin

Install as a Claude Code plugin to use craft across any project:

From the terminal or /plugin within Claude Code:

claude plugin marketplace add gustin/craft-cli
claude plugin install craft@gustin-marketplace --scope project

After pushing new versions, update from the terminal or /plugin:

claude plugin marketplace update gustin-marketplace
claude plugin update craft@gustin-marketplace --scope project

Restart Claude Code after installing or updating for changes to take effect.

The plugin provides skills that let Claude browse, read, write, and render Craft docs. Set CRAFT_API_KEY and CRAFT_API_BASE in your shell environment.

Requirements

• bash, curl, jq
• node 24+ and npm install (for mermaid rendering)
• Craft.do API connection (docs)

License

MIT