在终端里跑 TinyOwl（也给 AI 编程助手用）

版本说明：本文基于 TinyOwl v0.8.x 核对；适用于 macOS 12 及以上的 Apple 芯片 Mac。

和桌面版同一套工作流，无窗口运行

日常用桌面版时，TinyOwl 首页 那套体验很直接：把尺寸、本地压缩和可选上传串成一条工作流，截图后按 Command + V，或把文件拖进窗口就能跑完。

不过自动化场景里，点窗口就不太合适了：

• 文档与网站静态构建： 博客发版或静态站点打包前，希望由构建脚本自动优化 public 或 assets 目录下的所有新配图。
• 本地代码库 Git Hook： 在提交包含大图的 Pull Request 之前，自动拦截并按团队规范完成压缩。
• AI 编程助手协作： 使用 Cursor Agent、Claude Code 或 Codex 编写技术文档和前端页面时，让助手直接在终端调用本地工具处理图片并产出 Markdown 链接。

如果另写一套 Node 或 Python 脚本，既要维护 Sharp 这类本地依赖，又要重新配质量参数和云存储密钥。

TinyOwl 命令行直接复用你在桌面端已经调好的同一套工作流。带参数运行时不会弹出主窗口，不会激活程序坞，不会常驻菜单栏，也不会加载 WebView，用完就退出。

更完整的参数列表与选项，可以参阅命令行工具使用指南。

一键安装，无需 sudo

TinyOwl 只有一个应用包、一个可执行文件。双击打开是图形界面；在终端带参数调用同一个文件，就是命令行模式。

启用命令非常简单：

1. 首次打开 TinyOwl 桌面端时，应用会弹窗询问是否一键启用命令行。
2. 平时也可以随时进入 设置 → 基本设置 → 命令行工具 进行安装或卸载。

无论哪种方式，都只在 ~/.local/bin/tinyowl 创建一个指向应用包内可执行文件的符号链接。

整个安装过程遵循安全原则：

• 从不调用 sudo，也不要求任何管理员密码。
• 从不修改 Shell 配置文件（例如 ~/.zshrc 或 ~/.bashrc）。
• 从不覆盖已有文件，若已有同名文件或属于其他工具的链接，绝不强行替换。

如果你的系统尚未将 ~/.local/bin 加入环境变量，应用界面会直接提示需要添加到 PATH 的确切路径。

如果你习惯用脚本配置新 Mac 工作机，可以直接通过应用包执行无人值守安装：

/Applications/TinyOwl.app/Contents/MacOS/TinyOwl cli install

如果日后想移除命令，卸载指令只会清理 TinyOwl 自己创建的符号链接：

tinyowl cli uninstall

三条真实命令与真实 JSON

命令行的输入输出尽量稳定、可解析。下面三条分别是：列出工作流、预演、正式运行。

1. 查询当前可用的工作流列表

通过 --json 参数可以快速获取本机已配置的工作流定义：

tinyowl workflows list --json

{
  "ok": true,
  "workflows": [
    { "id": "workflow-compress-only", "name": "只压缩" },
    { "id": "workflow-compress-and-upload", "name": "压缩并上传" },
    { "id": "workflow-resize-compress-and-upload", "name": "调整后上传" }
  ]
}

传入 --json 时，stdout 只输出一条 JSON；进度和诊断信息都走 stderr。英文界面下，中文工作流名称也会原样保留；机器标识用稳定的工作流 ID（例如 workflow-compress-only）。

2. 通过 dry-run 模拟执行计划

在正式写入磁盘或发起网络请求之前，你可以先查看执行计划：

tinyowl run workflow-compress-only ~/Pictures/TinyOwl-demo.png --dry-run --json

{
  "ok": true,
  "dryRun": true,
  "plan": {
    "workflow": { "id": "workflow-compress-only", "name": "只压缩" },
    "inputCount": 1,
    "items": [
      {
        "path": "~/Pictures/TinyOwl-demo.png",
        "plannedOutputPath": "~/Desktop/zipic/73e34bef.png",
        "supported": true
      }
    ],
    "compression": { "quality": 75, "outputFormat": "original" },
    "license": { "authorized": true, "required": false }
  }
}

计划里能看到输入文件、计划输出路径、是否支持该格式、压缩质量与输出格式，以及当前是否已授权。

3. 正式运行工作流

确认无误后，指定目标图片与输出目录即可执行：

tinyowl run workflow-compress-only ~/Pictures/TinyOwl-demo.png --output-dir ~/Pictures/optimized

处理后的图片会写到 ~/Pictures/optimized。整批成功时退出码是 0。传入文件夹时会按固定顺序递归扫描，不会跟随目录符号链接。

AI 编程助手如何调用

当前主流的 AI 编程助手（如 Cursor Agent、Claude Code 等）基本都是通过执行 Bash 工具调用命令行。但在调用传统 CLI 工具时，AI 经常会遇到几个痛点：终端 ANSI 颜色代码干扰解析、动态进度条混入输出流、遇到意外覆盖时工具原地等待用户交互等。

TinyOwl 命令行比较适合这种用法：

1. 标准流分开： 配合 --json，stdout 只有最终 JSON，没有颜色码或进度条，助手可以用 JSON.parse 或 jq 解析。
2. 退出码固定： 不用从文本里猜有没有报错，看退出码就行。
3. 不卡在交互上： 覆盖或裁剪这类操作不会挂起等你按回车，而是直接失败并返回专用退出码，避免 agent 卡住。
4. 可以先预演： 改项目静态资源前，先跑 --dry-run --json，确认输入和授权状态。

AI 编程助手用自带的终端工具直接调用 tinyowl 即可。

限制条件、安全标记与退出码

在无人值守脚本里跑，有几条边界要先知道：

安全标记与覆盖确认

• 覆盖原文件与裁剪保护： 若工作流配置了「覆盖源文件」或者包含固定比例的「裁剪画框」步骤，在命令行中执行必须显式添加 --yes 参数。未带 --yes 时命令会立即终止并返回退出码 4。
• 本地纯处理： 若某条工作流包含上传步骤，但你在 CI 或离线环境中只需要缩放和压缩，加上 --skip-upload 即可跳过云端传输。

授权边界

• 单张图片： 处理单张支持格式的图片遵循 TinyOwl 的免费规则。
• 批量处理： 批量需要与桌面端相同的有效许可证或试用。未授权时，批处理会失败，并返回需要授权类退出码（文档中为 3）。

隐私保护与存储凭证安全

• 配置来源： 命令行直接读取桌面端现有的 settings.json 配置文件。
• 不读钥匙串、不把密钥写进参数： 命令行不访问 macOS 钥匙串，也不接受把 Access Key、Secret Key 或 Session Token 当作参数传入，避免密钥进 shell 历史、进程列表或 agent 日志。
• 只输出是否就绪： 输出里只有就绪状态这类布尔值，不打印密钥；云服务返回的错误也会先打码再输出。

完整退出码对照表

脚本和 AI 工具可以按这些退出码分支：

稳定的 JSON、明确的安全边界和固定退出码，让桌面端调好的工作流也能直接进脚本和 AI 编程对话。