1. 项目概述与核心价值如果你和我一样是个喜欢在命令行里敲敲打打、追求极致效率的博主那么今天分享的这个工具你一定会爱不释手。它叫bearblog-cli一个非官方的、用 Python 写的命令行工具专门用来管理你在 BearBlog 上的文章。BearBlog 本身就是一个极简、注重隐私的博客平台没有花哨的界面只有纯粹的写作。而这个 CLI 工具则把这种“纯粹”延伸到了你的终端里。简单来说有了它你就不再需要频繁打开浏览器登录 BearBlog 的网页后台去创建、查看或删除文章了。所有操作都可以在你熟悉的终端里用几条命令搞定。这对于习惯用 Markdown 写作、喜欢用 Git 管理内容、或者希望通过脚本自动化发布流程的开发者来说简直是福音。我自己在深度使用了几周后写作和内容管理的效率提升非常明显尤其是当需要批量处理草稿或者从本地文档库同步文章时。这个工具的核心价值就是将内容创作与管理流程无缝集成到开发者的工作流中。它特别适合以下几类人一是技术博主习惯用 VS Code 或 Vim 写 Markdown二是希望将博客内容纳入版本控制如 Git的人三是正在构建自动化内容管道比如结合 AI 助手如项目提到的 OpenClaw生成初稿后自动发布。接下来我就结合自己的实操经验带你从零开始彻底玩转这个工具。2. 环境准备与工具安装工欲善其事必先利其器。bearblog-cli的安装非常简单但有几个关键配置点需要注意这直接关系到工具能否正常运行。2.1 获取项目代码与依赖安装首先你需要把项目的代码拿到本地。通常有两种方式直接克隆仓库推荐如果你熟悉 Git这是最好的方式便于后续更新。git clone https://github.com/primaryobjects/bearblog-cli.git cd bearblog-cli下载 ZIP 包如果你不常用 Git可以直接在 GitHub 项目页面点击 “Code” - “Download ZIP”解压后进入目录。进入项目目录后下一步是安装 Python 依赖。项目根目录下有一个requirements.txt文件里面列出了所有必需的库。打开终端执行pip install -r requirements.txt这里有个实操心得强烈建议你使用 Python 的虚拟环境如venv或conda来安装依赖避免污染系统级的 Python 环境。你可以这样操作# 创建虚拟环境 python -m venv venv # 激活虚拟环境Linux/macOS source venv/bin/activate # 激活虚拟环境Windows venv\Scripts\activate # 然后在虚拟环境中安装依赖 pip install -r requirements.txt这样做的好处是项目的依赖被隔离在一个独立的环境中即使未来工具更新或依赖库变更也不会影响你系统上其他 Python 项目。2.2 关键配置.bearblog凭证文件安装完依赖最核心的一步来了——配置你的 BearBlog 账户信息。工具通过一个名为.bearblog的配置文件来读取你的登录凭证。你需要在项目根目录下创建这个文件。重要警告这个文件包含了你的邮箱和密码务必不要将其提交到任何公开的 Git 仓库中。你应该将它添加到.gitignore文件里。创建.bearblog文件内容格式如下EMAILyour-emailexample.com PASSWORDyour_password BLOG_NAMEyour-subdomain我们来拆解一下这三个参数EMAIL和PASSWORD就是你登录 BearBlog 网站时使用的邮箱和密码。BLOG_NAME这是你的博客子域名。如果你博客的地址是https://yourblog.bearblog.dev或https://bearblog.dev/yourblog那么yourblog就是你的BLOG_NAME。你可以在 BearBlog 后台的仪表盘 URL 里找到它。注意将密码明文写在文件里存在安全风险。虽然对于个人本地使用且文件已加入.gitignore的情况下风险可控但如果你非常在意可以考虑后续对工具进行改造使用环境变量或系统密钥链来管理密码。不过作为初始使用按上述方法配置是最直接的。配置完成后你可以运行python bearcli.py --help来测试工具是否安装成功。如果能看到帮助信息说明环境准备就绪。3. 核心功能详解与实战操作配置好环境我们就可以开始实战了。bearblog-cli提供了四个核心命令覆盖了文章管理的核心场景。我们一个一个来拆解并分享我使用过程中的技巧和踩过的坑。3.1 列出所有文章list命令当你忘记了自己写过哪些文章或者想快速查看文章的 ID 以便进行后续操作时list命令是你的好帮手。基本用法python bearcli.py list执行后工具会调用 BearBlog 的 API获取你账户下所有的文章列表并以 JSON 格式输出。输出内容大致如下[ { id: abc123xyz, title: 我的第一篇文章, href: /yourblog/dashboard/posts/abc123xyz/ }, { id: def456uvw, title: 关于Python虚拟环境的思考, href: /yourblog/dashboard/posts/def456uvw/ } ]字段解析与使用技巧id这是每篇文章在 BearBlog 系统中的唯一标识符。后续的load加载和delete删除命令都需要用到它。务必记好这个 ID或者在使用list后将其保存下来。title文章标题用于快速浏览。href文章在网页后台的完整路径。你可以将其与https://bearblog.dev拼接直接在浏览器中打开文章编辑页面。例如https://bearblog.dev/yourblog/dashboard/posts/abc123xyz/。实操心得默认的 JSON 输出虽然机器可读但对人眼并不友好。我通常会结合jq这个命令行 JSON 处理工具来美化输出或者只提取我关心的字段# 使用 jq 美化输出 python bearcli.py list | jq . # 只提取 ID 和标题 python bearcli.py list | jq -r .[] | \(.id): \(.title)如果你没有安装jq也可以考虑修改工具的源代码让list命令默认以表格形式输出这样会更直观。3.2 创建新文章new命令这是最常用的功能允许你将本地的 Markdown 文件直接发布为 BearBlog 上的一篇文章。基本语法python bearcli.py new “文章标题” --file 你的文件.md例如你有一篇写好的 Markdown 文件my_post.md想把它发布出去python bearcli.py new “深入理解BearBlog CLI” --file my_post.mdMarkdown 文件格式的奥秘 工具支持两种格式的 Markdown 文件带 Front Matter 的格式如果你熟悉 Jekyll 或 Hugo 等静态博客一定对 Front Matter 不陌生。它是一个位于文件顶部、用---包裹的 YAML 区块用于定义文章的元数据。--- title: 深入理解BearBlog CLI date: 2023-10-27 tags: [cli, blogging, python] --- 这里是文章的正文内容...优势信息结构化可以包含更多元数据如标签、分类、摘要等。工具会优先使用 Front Matter 里的title和date。注意目前 BearBlog 的 API 可能只支持title和date其他如tags的字段可能不会被处理但可以保留在文件里。纯 Markdown 格式文件开头就是正文。这里是文章的正文内容...工具的处理逻辑如果你没有提供 Front Matter工具会使用你在命令行中通过new “标题”指定的标题并将发布日期设置为当前日期。一个关键的避坑点编码问题。确保你的 Markdown 文件保存为UTF-8编码。如果文件中包含中文或其他非 ASCII 字符但文件是 GBK 或 ANSI 编码工具在上传时可能会报错或产生乱码。在 VS Code 中你可以通过右下角的状态栏查看和更改编码。高级用法与自动化设想new命令的本质是读取本地文件并调用 API 提交。这为自动化打开了大门。例如你可以写一个简单的 Shell 脚本监控某个目录下的新 Markdown 文件并自动调用bearcli.py new来发布。或者结合像 OpenClaw 这样的 AI 助手让 AI 生成文章草稿并保存为.md文件后自动触发发布流程。3.3 加载文章内容load命令有时我们需要查看线上某篇文章的具体内容或者将其备份到本地。load命令就是干这个的。基本用法python bearcli.py load abc123xyz你需要将abc123xyz替换为你要查看的文章的实际 ID可以从list命令的输出中获得。执行后工具会从 BearBlog 服务器获取该文章的完整内容包括可能的 Front Matter 和正文并打印在终端里。你可以通过重定向操作符将其保存到本地文件python bearcli.py load abc123xyz backup_post.md这样你就完成了一次简单的文章备份。使用场景分析内容恢复如果你不小心在本地删除了文章的原始 Markdown 文件可以从线上重新拉取。跨设备写作在另一台电脑上你可以快速拉取正在编辑的文章继续工作。批量备份可以写一个脚本循环调用list获取所有文章 ID然后逐一调用load将全部文章备份到本地实现博客的完整归档。3.4 删除文章delete命令这是一个需要谨慎使用的命令因为它会永久删除文章。基本用法python bearcli.py delete abc123xyz同样abc123xyz需要替换为目标文章的 ID。重要警告与安全建议没有回收站BearBlog 的删除操作很可能是直接、永久的。执行前请务必确认文章 ID 是否正确。双重确认原工具没有提供二次确认提示。为了安全起见我强烈建议你在使用delete命令前先使用load命令查看一下该 ID 对应的文章标题和内容做最终确认。备份优先在删除任何文章之前尤其是重要的文章请先使用load命令将其内容备份到本地。养成“删前先备”的习惯。一个更安全的做法是你可以修改工具的源代码为delete命令增加一个交互式的确认环节或者强制要求先备份才能删除。4. 集成与自动化实战案例命令行工具的强大之处在于易于集成和脚本化。下面我分享两个将bearblog-cli融入实际工作流的案例。4.1 案例一构建本地博客写作与发布流水线我的个人工作流是这样的写作在~/Documents/my_blog/posts/目录下用 Obsidian 或 VS Code 写 Markdown。每篇文章一个文件文件名即文章标题英文或拼音例如getting-started-with-bearblog-cli.md。版本控制该目录本身就是一个 Git 仓库每完成一篇文章或一次修改就进行提交。这相当于一个本地的、带版本历史的文章库。发布脚本我编写了一个简单的 Shell 脚本publish.sh来自动化发布过程。#!/bin/bash # publish.sh POST_FILE$1 POST_TITLE$(basename “$POST_FILE” .md | sed ‘s/-/ /g’) # 将文件名中的‘-’替换为空格作为标题 if [ ! -f “$POST_FILE” ]; then echo “文件不存在: $POST_FILE” exit 1 fi echo “准备发布文章$POST_TITLE” echo “文件路径$POST_FILE” read -p “是否确认发布(y/N): “ -n 1 -r echo if [[ $REPLY ~ ^[Yy]$ ]]; then cd /path/to/bearblog-cli # 切换到你的 CLI 工具目录 python bearcli.py new “$POST_TITLE” --file “$POST_FILE” echo “发布指令已执行。” else echo “已取消发布。” fi使用方式./publish.sh ~/Documents/my_blog/posts/my-new-post.md。这个脚本会自动从文件名生成一个可读的标题并在我确认后调用bearblog-cli发布。草稿管理我还有一个drafts/子目录。只有当我决定正式发布时才将文件从drafts/移动到posts/并运行发布脚本。这个流程将写作、版本管理和发布解耦既安全又高效。4.2 案例二与 OpenClaw 等 AI 助手结合项目描述里特别提到了 OpenClaw。这指向了一个更前沿的用法AI 辅助内容创作与自动发布。设想一个场景你向 OpenClaw 发出指令“写一篇关于 Python 列表推导式的技术博客500字左右。”OpenClaw 生成一篇结构完整、内容可用的 Markdown 文章并保存为list-comprehension.md。一个监听脚本或 OpenClaw 自身的技能检测到新文件生成自动调用bearcli.py new “Python列表推导式详解” --file list-comprehension.md。文章被自动发布到你的 BearBlog整个过程无需人工干预。这需要 OpenClaw 具备文件系统操作和调用外部命令的能力。如果配置得当你可以建立一个“命题作文 - AI 生成 - 自动发布”的管道极大提升内容产出的效率。当然目前 AI 生成的内容通常需要人工审核和润色但至少初稿的创建和上传环节可以完全自动化。5. 常见问题排查与进阶技巧即使工具简单在实际使用中也可能遇到一些问题。下面是我遇到的一些典型情况及解决方法。5.1 连接与认证失败问题现象执行任何命令都报错提示认证失败、网络错误或返回非200状态码。排查步骤检查.bearblog文件首先确认文件是否在项目根目录且名称正确前面有点号。检查邮箱、密码、BLOG_NAME是否填写正确特别注意密码是否有特殊字符需要转义通常不需要。BLOG_NAME是子域名不包含bearblog.dev。检查网络连接确保你的网络可以正常访问https://bearblog.dev。如果处在受限网络环境可能会失败。验证 BearBlog 账户用浏览器登录 BearBlog 后台确认账户状态正常密码无误。查看工具源码打开bearcli.py找到发送请求的部分通常是使用requests库的post或get方法。你可以临时添加几行打印语句输出请求的 URL 和头部信息看看是否和你预期的一致。# 在源码的请求函数中添加调试信息 import requests response requests.post(url, jsondata, headersheaders) print(“Debug: Request URL:“, url) # 临时添加 print(“Debug: Response Status Code:“, response.status_code) # 临时添加 print(“Debug: Response Text:“, response.text) # 临时添加5.2 文章内容乱码或格式错误问题现象发布后的文章在网页上显示乱码或者 Markdown 格式如代码块、列表没有正确渲染。排查步骤文件编码这是最常见的原因。100% 确保你的 Markdown 文件是UTF-8 without BOM编码。在 Windows 的记事本中另存为时可以选择“UTF-8”在 VS Code/Sublime 等编辑器中确保底部状态栏显示“UTF-8”。特殊字符检查文件中是否包含一些需要转义的特殊字符。虽然标准的 Markdown 和 HTML 字符在 BearBlog 中通常没问题但极端情况下可能需要处理。Front Matter 格式如果你使用了 Front Matter确保三个连字符---的上方和下方没有多余的空格或字符且 YAML 语法正确。一个错误的缩进都可能导致整个 Front Matter 被当作正文处理。直接测试将出问题的 Markdown 内容手动复制到 BearBlog 网页编辑器的“源代码”模式如果有或直接粘贴看是否正常。如果网页正常而 CLI 不正常问题很可能出在 CLI 的请求封装或编码处理上。5.3 命令执行缓慢或无响应问题现象执行list或new命令后终端卡住很久才有响应或超时。排查步骤网络延迟BearBlog 的服务器可能在海外网络延迟可能导致请求变慢。这是正常现象尤其是第一次请求时。文章数量如果你有非常多的文章比如上百篇list命令获取所有数据可能需要一些时间。超时设置默认情况下Pythonrequests库没有设置超时。如果网络不稳定请求可能会挂起。你可以修改bearcli.py的源码在requests调用中增加timeout参数例如requests.get(url, headersheaders, timeout10)这样10秒后就会抛出超时异常而不是无限等待。5.4 进阶技巧改造与增强原生工具开源工具的好处是可以按需定制。如果你觉得原生功能不够用这里有一些增强思路增加更新Update命令原生工具缺少更新已有文章的功能。你可以研究 BearBlog 的 API实现一个update命令通过文章 ID 和新的 Markdown 文件内容来更新线上文章。增加文章状态筛选list命令目前列出所有文章。可以增加参数如--status draft或--status published只列出特定状态的文章。输出格式美化将默认的 JSON 输出改为更易读的纯文本表格类似ls -la的样式。配置方式增强将敏感的密码信息从.bearblog文件中移出改用环境变量如BEARBLOG_PASSWORD或系统密钥链来存储提升安全性。错误处理与日志增加更详细的错误日志将运行信息写入日志文件方便排查问题。要实现这些你需要有一定的 Python 编程能力并可能需要通过浏览器开发者工具研究 BearBlog 网页端发出的网络请求来模拟其 API 调用。这是一个很好的学习项目能让你深入理解如何与 Web API 交互。