nerveband-craft-cli

Craft CLI 笔记与文档管理：创建、搜索、链接与导出 Craft 文档。

## 概述（中文）

Craft CLI 笔记与文档管理：创建、搜索、链接与导出 Craft 文档。

## 技能正文

# Craft CLI 技能

通过 `craft` CLI 工具与 Craft Documents 交互。快速、节省 token、为 LLM 而生。

## 安装

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

若未安装：
```bash
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 空间（业务）
```bash
~/clawd/skills/craft-cli/craft config set-api https://connect.craft.do/links/5VruASgpXo0/api/v1
```

### 个人空间
```bash
~/clawd/skills/craft-cli/craft config set-api https://connect.craft.do/links/HHRuPxZZTJ6/api/v1
```

### 快速切换（辅助脚本）
```bash
# 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
```

**检查当前配置：**
```bash
~/clawd/skills/craft-cli/craft config get-api
```

## 命令

### 列出文档
```bash
# 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
```

### 搜索文档
```bash
# Search for documents
~/clawd/skills/craft-cli/craft search "query terms"

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

### 获取文档
```bash
# 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
```

### 创建文档
```bash
# 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>
```

### 更新文档
```bash
# 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
```

### 删除文档
```bash
~/clawd/skills/craft-cli/craft delete <document-id>
```

### 信息命令
```bash
# Show API info and recent documents
~/clawd/skills/craft-cli/craft info

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

### 版本
```bash
~/clawd/skills/craft-cli/craft version
```

## 输出格式

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

在配置中设置默认格式，或对每条命令使用 `--format` 标志。

## API URL 覆盖

为任何命令覆盖已配置的 API URL：
```bash
~/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` —— 缺少配置

## 用法示例

### 工作流：列出与搜索
```bash
# 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
```

### 工作流：创建与更新
```bash
# 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
```

### 工作流：导出文档
```bash
# Get a specific document and save to file
~/clawd/skills/craft-cli/craft get <doc-id> --output exported-notes.md
```

### LLM 集成
```bash
# 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'
```

## 提示

1. **默认使用 JSON 格式**以供 LLM 消费（这是默认值）
2. **使用 table 格式**向人类展示结果
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