Craft CLI

Manage Craft documents via the craft CLI tool, supporting listing, searching, creating, updating, deleting, and exporting in JSON, table, or markdown formats.

Security Scan

The skill broadly matches a Craft CLI integration, but contains multiple inconsistencies (missing binary, mismatched versions, conflicting install paths) and embeds API URLs that look like pre-authorized links — these warrant review before use.

Purpose & Capability

The skill claims to integrate with the Craft CLI. That purpose is plausible, but the package asserts the craft binary is included in documentation/README while no binary is present in the file manifest. SKILL.md and README reference a craft binary and provide installation instructions, yet the helper script expects the binary at $HOME/clawd/skills/craft-cli/craft while SKILL.md recommends /usr/local/bin/craft. The registry version (1.6.2) disagrees with SKILL.md (1.6.0) and the install example (v1.0.0). These inconsistencies mean the files provided do not cleanly align with the stated purpose.

Instruction Scope

Runtime instructions are narrowly focused on using the craft CLI (list/search/get/create/update/delete). They tell the agent how to install and configure an API URL and include helper commands. No instructions ask the agent to read or exfiltrate unrelated host files or environment variables. However, the SKILL.md and helper script embed two specific API URLs (wavedepth and personal), which are external endpoints and likely carry access tokens in the URL — that is a scope decision (using pre-authorized links) that may be unexpected for users.

Install Mechanism

There is no install spec in the skill bundle (instruction-only), which is lower risk. The SKILL.md suggests downloading a binary from a GitHub release (a known host) but the release tag in the example (v1.0.0) doesn't match the registry version. The example binary is darwin-arm64 only, yet the skill has no OS restriction. Overall the install instructions are plausible but inconsistent and could mislead users into running the wrong binary for their platform.

Credentials

The skill declares no required env vars or credentials, which is reasonable for a CLI wrapper. But it includes hard-coded API URLs in SKILL.md and in craft-helper.sh (WAVEDEPTH_API, PERSONAL_API). Those URLs likely embed access tokens/links to specific Craft spaces. Embedding pre-authorized links for a 'personal' space is disproportionate: users should be alerted that the skill will configure the CLI to point at third-party spaces and should verify if those links are intended or sensitive.

Persistence & Privilege

The skill does not request persistent agent privileges (always: false) and is user-invocable. It does not modify other skills' configurations. No elevated platform privileges are declared.

What to consider before installing

What to check before installing: - Do not run the curl | chmod | sudo mv commands blindly. Verify the GitHub release URL and checksum for the binary that matches your OS/arch. The example downloads v1.0.0 darwin-arm64 but the skill registry lists v1.6.2 — confirm which binary you need. - The package manifest does not include a craft binary even though README and SKILL.md mention one. Expect to supply or install the binary yourself via the official project releases. - The helper script assumes the binary lives at ~/clawd/skills/craft-cli/craft; SKILL.md recommends /usr/local/bin/craft. Decide where you will place the binary and edit the helper script or PATH accordingly. - The skill contains two hard-coded API URLs (wavedepth and personal). Those look like pre-authorized links and may grant access to remote documents owned by the skill author. If you do not want your CLI configured to use those endpoints, do not run the helper script and instead set your own API URL via 'craft config set-api <url>'. - Prefer installing the craft CLI from the official repository and verifying signature/checksum. If you proceed, inspect the helper script (it's short and readable) and replace embedded API links with your own or remove them. If you want, I can: - extract and summarize all inconsistencies (versions, paths) in a short checklist you can present to the maintainer; - show exactly what to edit in craft-helper.sh so it uses /usr/local/bin/craft or $PATH instead of a hard-coded $HOME path.

Craft CLI Skill

Interact with Craft Documents via the craft CLI tool. Fast, token-efficient, LLM-ready.

Installation

The craft CLI binary should be installed at /usr/local/bin/craft.

If not installed:

curl -L https://github.com/nerveband/craft-cli/releases/download/v1.0.0/craft-darwin-arm64 -o craft
chmod +x craft
sudo mv craft /usr/local/bin/

Configuration

Two Craft spaces are available:

wavedepth Space (Business)

~/clawd/skills/craft-cli/craft config set-api https://connect.craft.do/links/5VruASgpXo0/api/v1

Personal Space

~/clawd/skills/craft-cli/craft config set-api https://connect.craft.do/links/HHRuPxZZTJ6/api/v1

Quick Switch (Helper Script)

# Switch to wavedepth space
~/clawd/skills/craft-cli/craft-helper.sh wavedepth

# Switch to personal space
~/clawd/skills/craft-cli/craft-helper.sh personal

# Check current space
~/clawd/skills/craft-cli/craft-helper.sh current

Check current configuration:

~/clawd/skills/craft-cli/craft config get-api

Commands

List Documents

# JSON format (default - LLM-friendly)
~/clawd/skills/craft-cli/craft list

# Human-readable table
~/clawd/skills/craft-cli/craft list --format table

# Markdown format
~/clawd/skills/craft-cli/craft list --format markdown

Search Documents

# Search for documents
~/clawd/skills/craft-cli/craft search "query terms"

# With table output
~/clawd/skills/craft-cli/craft search "query" --format table

Get Document

# Get document by ID (JSON)
~/clawd/skills/craft-cli/craft get <document-id>

# Save to file
~/clawd/skills/craft-cli/craft get <document-id> --output document.md

# Different format
~/clawd/skills/craft-cli/craft get <document-id> --format markdown

Create Document

# Create with title only
~/clawd/skills/craft-cli/craft create --title "My New Document"

# Create from file
~/clawd/skills/craft-cli/craft create --title "My Document" --file content.md

# Create with inline markdown
~/clawd/skills/craft-cli/craft create --title "Quick Note" --markdown "# Hello\nThis is content"

# Create as child of another document
~/clawd/skills/craft-cli/craft create --title "Child Doc" --parent <parent-id>

Update Document

# Update title
~/clawd/skills/craft-cli/craft update <document-id> --title "New Title"

# Update from file
~/clawd/skills/craft-cli/craft update <document-id> --file updated-content.md

# Update with inline markdown
~/clawd/skills/craft-cli/craft update <document-id> --markdown "# Updated\nNew content"

# Update both title and content
~/clawd/skills/craft-cli/craft update <document-id> --title "New Title" --file content.md

Delete Document

~/clawd/skills/craft-cli/craft delete <document-id>

Info Commands

# Show API info and recent documents
~/clawd/skills/craft-cli/craft info

# List all available documents
~/clawd/skills/craft-cli/craft docs

Version

~/clawd/skills/craft-cli/craft version

Output Formats

• json (default): Machine-readable JSON, ideal for LLMs and scripts
• table: Human-readable table format
• markdown: Markdown-formatted output

Set default format in config or use --format flag per command.

API URL Override

Override the configured API URL for any command:

~/clawd/skills/craft-cli/craft list --api-url https://connect.craft.do/links/ANOTHER_LINK/api/v1

Error Handling

The CLI provides clear error messages with exit codes:

• Exit Code 0: Success
• Exit Code 1: User error (invalid input, missing arguments)
• Exit Code 2: API error (server-side issues)
• Exit Code 3: Configuration error

Common errors:

• authentication failed. Check API URL - Invalid/unauthorized API URL
• resource not found - Document ID doesn't exist
• rate limit exceeded. Retry later - Too many requests
• no API URL configured. Run 'craft config set-api <url>' first - Missing config

Usage Examples

Workflow: List and Search

# List all documents in wavedepth space
~/clawd/skills/craft-cli/craft config set-api https://connect.craft.do/links/5VruASgpXo0/api/v1
~/clawd/skills/craft-cli/craft list --format table

# Search for specific documents
~/clawd/skills/craft-cli/craft search "proposal" --format table

Workflow: Create and Update

# Create a new document
~/clawd/skills/craft-cli/craft create --title "Project Notes" --markdown "# Initial notes\n\nStart here."

# Get the document ID from output, then update
~/clawd/skills/craft-cli/craft update <doc-id> --title "Updated Project Notes"

# Verify the update
~/clawd/skills/craft-cli/craft get <doc-id> --format markdown

Workflow: Export Document

# Get a specific document and save to file
~/clawd/skills/craft-cli/craft get <doc-id> --output exported-notes.md

LLM Integration

# Get all documents as JSON (pipe to processing)
~/clawd/skills/craft-cli/craft list | jq '.[] | {id, title}'

# Search and extract specific fields
~/clawd/skills/craft-cli/craft search "meeting" | jq '.[].title'

Tips

1. Default to JSON format for LLM consumption (it's the default)
2. Use table format when showing results to humans
3. Check configuration before operations: craft config get-api
4. Switch spaces easily with craft config set-api <url>
5. Override API URL temporarily with --api-url flag instead of changing config

GitHub Repository

Source code and documentation: https://github.com/nerveband/craft-cli

Version

Current version: 1.6.0