使用指南

命令行工具

TinyOwl 自带一个 macOS 应用和一个可执行文件。平时打开应用会进入桌面界面。带参数调用这个可执行文件时，会无窗口运行：不激活程序坞，不建立菜单栏托盘，也不加载 WebView。

安装命令

首次启动时，TinyOwl 会询问是否一键启用命令行。之后也可以在 设置 → 基本设置 → 命令行工具 里安装或卸载。

两种方式都会在 ~/.local/bin/tinyowl 放一个指向当前应用可执行文件的符号链接。安装过程不会使用 sudo，不会要求密码，不会改 shell 配置，也不会覆盖已有文件或其他应用的符号链接。

如果要无人值守安装，可以直接从应用包跑同一套安装：

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

如果 ~/.local/bin 还不在 PATH 里，TinyOwl 会提示需要加入的目录。加好之后，才能直接用 tinyowl 这个命令。

只想去掉当前 TinyOwl 应用自己创建的链接时：

tinyowl cli uninstall

命令

tinyowl --version
tinyowl workflows list
tinyowl workflows list --json
tinyowl workflows show workflow-compress-only
tinyowl inspect ~/Pictures/example.png --json
tinyowl run workflow-compress-only ~/Pictures/example.png --output-dir ~/Pictures/optimized
tinyowl run "Resize & Upload" ~/Pictures/post-images --dry-run --json
tinyowl run workflow-compress-and-upload image.png --skip-upload --output-dir ./out

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、预览与退出码

--json 只往 stdout 写一份 JSON。诊断信息和进度写到 stderr。

--dry-run 只描述覆盖、裁剪、上传、输出路径、存储是否就绪，以及是否需要授权。它不写文件，也不连接存储。下面是「只压缩」工作流的一次真实预览，路径已缩短：

{
  "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 }
  }
}

退出码是稳定的：

退出码	含义
`0`	成功
`2`	用法或配置错误
`3`	需要授权
`4`	需要确认
`5`	部分失败
`6`	整批执行失败
`7`	工作流名称有歧义

批次里只有一部分文件失败时，会返回每个文件的结果，并以退出码 5 结束。

安全与授权

会覆盖源文件或裁剪图片的工作流，需要加上 --yes。
--skip-upload 只执行本机的尺寸调整和压缩。
单张受支持的图片沿用 TinyOwl 的免费行为。批量处理需要与桌面应用相同的有效许可证或试用。

隐私与凭证

命令行读取的是桌面应用已有的 settings.json。它不使用钥匙串，也不接受把存储凭证写进命令参数。

工作流和上传目标的输出只给出是否就绪的布尔值，不会打印 Access Key、Secret Key 或 Session Token。存储服务返回的错误会先打码，再进入 stdout、stderr 或 TinyOwl 日志。