Craft CLI 技能

通过 craft CLI 工具与 Craft 文档交互。快速、高效、适用于 LLM。

安装

craft CLI 二进制文件应安装在 /usr/local/bin/craft。

如果尚未安装：

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/

配置

提供两个 Craft 空间：

wavedepth 空间（业务）

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

个人空间

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

快速切换（辅助脚本）

# 切换到 wavedepth 空间
~/clawd/skills/craft-cli/craft-helper.sh wavedepth

# 切换到个人空间
~/clawd/skills/craft-cli/craft-helper.sh personal

# 检查当前空间
~/clawd/skills/craft-cli/craft-helper.sh current

检查当前配置：

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

命令

列出文档

# JSON 格式（默认 - 适合 LLM）
~/clawd/skills/craft-cli/craft list

# 人类可读的表格
~/clawd/skills/craft-cli/craft list --format table

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

搜索文档

# 搜索文档
~/clawd/skills/craft-cli/craft search "查询词"

# 使用表格输出
~/clawd/skills/craft-cli/craft search "查询" --format table

获取文档

# 通过 ID 获取文档（JSON）
~/clawd/skills/craft-cli/craft get <文档-id>

# 保存到文件
~/clawd/skills/craft-cli/craft get <文档-id> --output document.md

# 不同格式
~/clawd/skills/craft-cli/craft get <文档-id> --format markdown

创建文档

# 仅创建标题
~/clawd/skills/craft-cli/craft create --title "我的新文档"

# 从文件创建
~/clawd/skills/craft-cli/craft create --title "我的文档" --file content.md

# 使用内联 Markdown 创建
~/clawd/skills/craft-cli/craft create --title "快速笔记" --markdown "# 你好\n这是内容"

# 作为另一文档的子文档创建
~/clawd/skills/craft-cli/craft create --title "子文档" --parent <父文档-id>

更新文档

# 更新标题
~/clawd/skills/craft-cli/craft update <文档-id> --title "新标题"

# 从文件更新
~/clawd/skills/craft-cli/craft update <文档-id> --file updated-content.md

# 使用内联 Markdown 更新
~/clawd/skills/craft-cli/craft update <文档-id> --markdown "# 已更新\n新内容"

# 同时更新标题和内容
~/clawd/skills/craft-cli/craft update <文档-id> --title "新标题" --file content.md

删除文档

~/clawd/skills/craft-cli/craft delete <文档-id>

信息命令

# 显示 API 信息和最近文档
~/clawd/skills/craft-cli/craft info

# 列出所有可用文档
~/clawd/skills/craft-cli/craft docs

版本

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

输出格式

• json（默认）：机器可读的 JSON，适合 LLM 和脚本
• table：人类可读的表格格式
• markdown：Markdown 格式的输出

可在配置中设置默认格式，或为每个命令使用 --format 标志。

API URL 覆盖

为任何命令临时覆盖已配置的 API URL：

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

错误处理

CLI 提供清晰的错误信息和退出码：

• 退出码 0：成功
• 退出码 1：用户错误（无效输入、缺少参数）
• 退出码 2：API 错误（服务器端问题）
• 退出码 3：配置错误

常见错误：
- authentication failed. Check API URL - 无效/未授权的 API URL
- resource not found - 文档 ID 不存在
- rate limit exceeded. Retry later - 请求过多
- no API URL configured. Run 'craft config set-api <url>' first - 缺少配置

使用示例

工作流：列出与搜索

# 列出 wavedepth 空间中的所有文档
~/clawd/skills/craft-cli/craft config set-api https://connect.craft.do/links/5VruASgpXo0/api/v1
~/clawd/skills/craft-cli/craft list --format table

# 搜索特定文档
~/clawd/skills/craft-cli/craft search "proposal" --format table

工作流：创建与更新

# 创建新文档
~/clawd/skills/craft-cli/craft create --title "项目笔记" --markdown "# 初始笔记\n\n从这里开始。"

# 从输出中获取文档 ID，然后更新
~/clawd/skills/craft-cli/craft update <doc-id> --title "更新的项目笔记"

# 验证更新
~/clawd/skills/craft-cli/craft get <doc-id> --format markdown

工作流：导出文档

# 获取特定文档并保存到文件
~/clawd/skills/craft-cli/craft get <doc-id> --output exported-notes.md

LLM 集成

# 将所有文档作为 JSON 获取（管道传输到处理程序）
~/clawd/skills/craft-cli/craft list | jq '.[] | {id, title}'

# 搜索并提取特定字段
~/clawd/skills/craft-cli/craft search "meeting" | jq '.[].title'

提示

1. LLM 使用默认 JSON 格式（它是默认设置）
2. 向人类展示结果时使用表格格式
3. 操作前检查配置：craft config get-api
4. 使用 craft config set-api <url> 轻松切换空间
5. 使用 --api-url 标志临时覆盖 API URL，而不是更改配置

GitHub 仓库

源代码和文档：https://github.com/nerveband/craft-cli

版本

当前版本：1.6.0