# tyndall-blog-cli

**Repository Path**: woohe/tyndall-blog-cli

## Basic Information

- **Project Name**: tyndall-blog-cli
- **Description**: Blog CLI for Tyndall：从源码安装，用 Markdown 管理文章，并学习通用命令行工作流。
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-15
- **Last Updated**: 2026-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Blog CLI for Tyndall

用 Markdown、Git 式子命令和明确的状态转换管理 Tyndall 文章。项目同时保留 `tyndall-mcp` 入口，供兼容的 AI 客户端使用。

- 官网教程：<https://wanoohe.top/blog/cli>
- 源码仓库：<https://gitee.com/Woohe/tyndall-blog-cli>
- 当前版本：`0.5.1`
- 许可证：GPL-3.0-only

Blog CLI 面向拥有兼容 Tyndall 站点和管理员账号的人。公开访客可以完成所有本地练习；登录、草稿和发布等远端操作需要站点权限。

## 从源码安装

安装前需要 Git、Node.js 20 或 22，以及 npm。这里不提供一键脚本：克隆、检查、构建和链接本身就是标准 CLI 上手过程。

```text
git clone https://gitee.com/Woohe/tyndall-blog-cli.git
cd tyndall-blog-cli
git status
npm install
npm run typecheck
npm test
npm run build
npm link
blog --version
blog --help
blog post --help
```

`npm install` 根据 `package-lock.json` 安装依赖；`typecheck/test/build` 分别检查类型、行为和可执行产物；`npm link` 把本仓库的 `blog` 与 `tyndall-mcp` 二进制加入当前 Node 环境。

如果 `blog` 不在 PATH，先运行 `npm prefix -g`，检查该目录对应的全局可执行文件目录是否在 PATH；切换 Node 版本管理器后通常需要重新执行 `npm link`。

## 不连接站点也能练习

```text
mkdir my-first-post
cd my-first-post
blog post init article.md
blog post validate article.md --local
blog post --help
```

`init` 和 `validate --local` 只操作本地文件。打开 `article.md` 可以看到 YAML frontmatter 和 Markdown 正文；CLI 不会因为尚未配置 API 而阻止这些命令。

## 配置与诊断

Blog CLI 没有内置生产站点。首次执行远端命令前必须明确设置兼容站点的 API 基点：

```text
blog config set api-base https://your-tyndall.example/blog
blog config get api-base
blog config list --show-origin
blog doctor
```

持久化配置位于 `~/.config/tyndall-mcp/config.json`。`api-base` 只接受 HTTP/HTTPS URL，查询参数、片段和尾部 `/` 会被规范化；包含用户名或密码的 URL 会被拒绝。

配置优先级固定为：

```text
BLOG_API_BASE > TYNDALL_API_BASE > 配置文件 > 未配置
```

环境变量适合当前 Shell 或 CI 的临时覆盖。`blog config set` 修改配置文件，但不会偷偷改父 Shell；因此 `config list --show-origin` 可能显示环境变量仍在覆盖刚写入的值。

## 登录与文章生命周期

```text
blog login
blog whoami
blog post validate article.md
blog post create article.md --dry-run
blog post create article.md
blog post list --status draft
blog post show 42
blog post pull 42 article.md
blog post diff 42 article.md
blog post update 42 article.md --note "补充示例"
blog post publish 42
blog logout
```

重要语义：

- `create` 只创建草稿，公开必须显式执行 `publish`。
- `--dry-run` 展示解析、映射和目标操作，不发送写请求。
- 发布、下线、回收、恢复和回滚会确认；非交互环境必须明确传入 `--yes`。
- `pull` 把远端状态变成可检查的本地文件，`diff` 只比较，`update` 才写远端。
- 更新携带 revision。远端已被他人修改时服务端返回 409，CLI 不静默覆盖。
- `--json` 把结构化数据写到 stdout；诊断和错误写到 stderr，失败使用非零退出码。

## Markdown 文档格式

```markdown
---
title: "文章标题"
slug: ""
lang: zh
description: ""
category: ""
tags: []
commentStatus: open
sticky: false
seoTitle: ""
seoDescription: ""
heroAlt: ""
translationKey: ""
revision: ""
---

在这里编写正文。
```

`category` 使用分类 slug，`tags` 使用标签名称。远端校验会把它们解析成后端 ID；未知值会报错，不自动创建。非法 YAML、缺少标题或编辑器异常退出时不会发送写请求，工作文件会保留。

## 命令发现方式

不要背完整命令表。像 Git、Docker 和 kubectl 一样逐级查看帮助：

```text
blog --help
blog config --help
blog post --help
blog post update --help
```

完整参考由构建后的 Commander 命令树生成在 `docs/command-reference.json`。修改命令后运行：

```text
npm run build
npm run reference:generate
npm run reference:check
```

## 更新与卸载

```text
cd tyndall-blog-cli
git fetch --tags
git status
git pull --ff-only
npm install
npm run typecheck
npm test
npm run build
npm link
```

卸载二进制：

```text
npm unlink -g tyndall-blog-cli
```

卸载不会自动删除 `~/.config/tyndall-mcp/`，因为其中可能有用户配置和令牌。确认不再需要后由用户自行删除。先执行 `blog logout` 可请求服务端注销并清除本地文件令牌。

## 开发验证

```text
npm run typecheck
npm test
npm run build
npm run reference:check
node dist/cli/index.js --help
node dist/cli/index.js post --help
```

模拟 API 测试不会访问生产站点。`npm run smoke` 是显式的远端 MCP 检查，需要先配置 API，并不属于默认 CI。

## 配置和秘密边界

| 名称 | 用途 |
| --- | --- |
| `BLOG_API_BASE` | 临时 API 基点，最高优先级 |
| `TYNDALL_API_BASE` | 兼容旧 MCP 配置的 API 基点 |
| `BLOG_CONFIG_FILE` | 覆盖 CLI 配置文件位置 |
| `BLOG_TOKEN` | 临时注入 access token |
| `BLOG_TOKEN_FILE` | 覆盖令牌文件位置 |
| `BLOG_EDITOR` | 编辑器命令，优先于 `VISUAL`、`EDITOR` |

不要把账号、密码、令牌或真实私有站点配置提交到仓库、日志或 Issue。详见 `SECURITY.md`。

## MCP 兼容入口

构建并链接后，原有二进制仍可用：

```text
tyndall-mcp
```

它与 `blog` 共用 API 配置、令牌存储、刷新和错误映射；原 MCP 工具名称不变。没有 API 配置时会明确报错，不再连接任何内置站点。