Craft文档的本地优先CLI：在符合条件时快速读取Craft Desktop缓存，REST备份，仅API写入。

单二进制 Bun CLI，AI 代理优先，运行于 macOS 和 Linux。还导出 TypeScript 库，用于 Raycast 和 Node 脚本。

非官方。与Craft Docs无关。

代理读策略： 在macOS上，保留craft source auto。未过滤的docs ls和简单的docs search先使用Craft的本地缓存，自动回退到REST。不要常规传递--api。Markdown文档读取也使用缓存。结构化/原始读取、任务、提醒、集合、过滤查询以及每次写入都使用REST。

---

安装（粘贴到你的AI代理）

要安装craft-cli，请将下面的模块粘贴到你的AI编码代理（Claude Code、Codex、OpenCode、Cursor等）。代理会处理克隆、构建、安装、认证和技能注册。

---

为了人类

本地优先的 Craft 文档CLI。主要目标是让 Craft 内容像 Obsidian 等工具中本地文件一样，易于从 AI 编码代理（Claude Code、Codex、OpenCode 等）读取和编辑。

craft-cli

Local-first CLI for Craft Docs: fast reads from Craft Desktop’s cache when eligible, REST fallback, and API-only writes.

Single-binary Bun CLI, AI-agent-first, runs on macOS and Linux. Also exports a TypeScript library for Raycast and Node scripts.

Unofficial. Not affiliated with Craft Docs.

Agent read policy: On macOS, keep craft source auto. Unfiltered docs ls and simple docs search use Craft’s local cache first and fall back to REST automatically. Do not pass --api routinely. Markdown document reads also use the cache. Structured/raw reads, tasks, reminders, collections, filtered queries, and every write use REST.

---

Install (paste this to your AI agent)

To install craft-cli, paste the block below into your AI coding agent (Claude Code, Codex, OpenCode, Cursor, etc.). The agent will handle clone, build, install, authentication, and skill registration.

You are installing craft-cli (https://github.com/pa1ar/craft-cli) for me. Use the latest public stable release and its matching bundled skill. Proceed end-to-end; ask only when a required choice or credential is missing.

1. RUNTIME CHECK
   Check whether `bun` is on PATH. If yes, continue.
   If not, use my stated package-manager preference, or install Bun from https://bun.sh. This project builds with Bun.

2. RELEASE + BUILD + INSTALL
   Resolve the latest public stable release:
   CRAFT_RELEASE_TAG="$(bun -e 'const r = await fetch("https://api.github.com/repos/pa1ar/craft-cli/releases/latest"); if (!r.ok) throw new Error("GitHub release lookup failed: " + r.status); const release = await r.json(); if (!release.tag_name || release.draft || release.prerelease) throw new Error("No stable release"); console.log(release.tag_name)')"
   Stop if that lookup fails. Do not silently install main or a local development binary.
   CRAFT_RELEASE_DIR="$HOME/.local/share/craft-cli/releases/$CRAFT_RELEASE_TAG"
   If the release directory already exists, preserve it. Verify its origin, tag commit and tracked source state before reuse; use a fresh directory if it has local edits.
   git clone --branch "$CRAFT_RELEASE_TAG" --depth 1 https://github.com/pa1ar/craft-cli.git "$CRAFT_RELEASE_DIR"
   cd "$CRAFT_RELEASE_DIR"
   Read this release's install.sh, then run ./install.sh.
   If install.sh fails, diagnose and report the failure before using its documented manual build/link equivalent. Keep the same release tag.
   Verify `~/.local/bin` is on PATH and `command -v craft` resolves to this release's binary. Add the PATH entry to my shell rc only if missing (detect zsh vs bash). Use `craft` from PATH for normal work.
   Record the release tag and `git rev-parse HEAD`; version alone does not prove a build came from a release.

3. CONNECTION