aktar CLI 文档

aktar upload

上传一个或多个文件，按顺序在每个文件完成时输出它的链接，每个文件一个。

用法

$ aktar upload <file>... [options]

选项

注意事项

• 上传前会先检查所有文件：只要有一个不存在，就不会上传任何文件，aktar 以退出码 2 退出。
• 某个文件上传失败时，其他文件仍会继续上传。每个失败都会输出到 stderr，退出码为 1。
• 不加 --folder 时，文件名由上传目标的路径模板决定，和拖到菜单栏上传完全一样。加上 --folder 时，文件会保留原名放进该文件夹。
• --name 一次只能用于一个文件。名称中的斜杠会被移除；如果名称没有扩展名，会自动加上原文件的扩展名：--name cover 会把 IMG_4021.jpg 上传为 cover.jpg。与 --folder 一起使用时，它就是文件夹中的文件名。
• --expires 接受 1、7、14 或 30（天），0 表示保留文件。不加时文件会保留，与 Aktar 中的删除时间设置无关。它需要该上传目标已设置 Aktar 的自动删除规则，且不能与 --folder 同时使用。
• --qr 不能与 --json 同时使用，--png 只能用于 aktar qr。
• 在终端中，上传进度会显示在 stderr 上。文件以流的方式传给 Aktar，所以文件大小不受影响，也没有时间限制。
• 如果上传目标在 Aktar 中设置了短链接服务，打印的就是短链接，--format 和 --qr 也会使用它。即使上传目标的规则会跳过这次上传，--short 也会创建短链接；--no-short 则不创建。如果 Aktar 无法创建，会打印原始链接，并在 stderr 中说明原因。

示例

$ aktar upload screenshot.png
https://files.example.com/2026/10/7f3c2a91.png

$ aktar upload *.png -f markdown
![](https://files.example.com/2026/10/1b9e44d0.png)
![](https://files.example.com/2026/10/c2f71a5e.png)

$ aktar upload IMG_4021.jpg --name cover --folder blog/2026
https://files.example.com/blog/2026/cover.jpg

$ aktar upload photo.jpg
aktar: photo.jpg: already uploaded, reused the existing link
https://files.example.com/2026/09/4d2a8c61.jpg

$ aktar upload talk.pdf --short
https://s.example.com/k3Tq9

aktar upload --clipboard

上传剪贴板中的文件或图片，效果与 Aktar 自带的剪贴板快捷键相同。

用法

$ aktar upload --clipboard [options]

选项

注意事项

• 传入文件或 --clipboard，二者只能选一。
• --name 和 --folder 只能用于文件。-d、-f、--expires、--qr 和 --json 的用法与上传文件时相同。
• 使用 --json 时仍然输出数组，其中只有一项。

示例

$ aktar upload --clipboard
https://files.example.com/2026/10/9a4c03be.png

$ aktar upload --clipboard -f markdown -d Blog
![](https://blog-assets.example.com/2026/10/e5b2c8a4.png)

$ aktar upload --clipboard --expires 1
https://files.example.com/tmp/1d/2026/10/38f0d7c2.png

aktar replace

用新文件覆盖一个已上传的文件，键和链接保持不变。拥有链接的人都会看到新文件。

用法

$ aktar replace <upload-id|link|key> <file> [options]

选项

注意事项

• 第一个参数是 aktar history 中的上传 ID 或链接（Aktar 的历史记录会随之更新），否则是 -d 所指目标存储桶中的键（省略 -d 时为 Aktar 中选中的目标）。不在 Aktar 历史记录中的链接会被拒绝，请改用 -d 并指定它的键。
• Aktar 会按目标设置移除文件的元数据并调整尺寸，但绝不会转换为其他格式，因此键的扩展名保持不变。位于 tmp/{N}d/ 下的文件会重新开始计算 N 天。
• 键不会被编号，也不会上传其他任何内容。--folder、--expires、--name 和 --clipboard 不适用，会被拒绝。
• 旧副本可能会在 CDN 缓存中保留一段时间。在 Aktar 中为目标开启 短缓存时间 或 Cloudflare 缓存清除即可解决。
• 需要 Aktar for Mac 0.14.0 或 Aktar for Windows 0.7.0 或更高版本。

示例

$ aktar replace 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 report-v2.pdf
https://files.example.com/2026/09/0e7d51b3.pdf

$ aktar replace docs/guide.pdf guide.pdf -d Blog -f markdown
[guide.pdf](https://blog-assets.example.com/docs/guide.pdf)

aktar short

用上传目标的短链接服务为上传记录中的某个上传创建短链接并打印出来。如果该上传已有短链接，就打印那一个。

用法

$ aktar short <upload-id|link> [--json | --qr]

选项

注意事项

• 传入上传 ID 或 aktar history 中的链接，短链接也可以。aktar 会在最近 1,000 个上传中查找。
• 上传目标需要在 Aktar 的短链接部分设置短链接服务：Shlink、YOURLS、Kutt、Dub、Short.io 或自定义请求。短链接由该服务创建，因此你的链接和点击数据都留在你自己的基础设施中。
• --json 会打印短链接的详细信息：服务商、状态，以及服务统计时的点击次数和最后点击时间。--qr 会附上它的二维码。两者不能同时使用。
• 需要 Mac 版 Aktar 0.17.0 或 Windows 版 Aktar 0.10.0。旧版本会回复尚不支持创建短链接。

示例

$ aktar short 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1
https://s.example.com/Qm3xZ

aktar qr

在终端中显示链接或任意文本的二维码，方便在手机上打开。传入上传 ID 时，会显示该上传的链接及其二维码。

用法

$ aktar qr <link|text|upload-id> [--png <file>]

选项

注意事项

• 只能传入一个参数，含空格的文本请加引号。
• 上传 ID 就是 aktar history --json 或 aktar upload --json 输出中的 id。aktar 会在 Aktar 上传记录的最近 1,000 条中查找它；如果是纯文本或链接，则完全不需要 Aktar。
• 无论终端使用什么主题，二维码都以白底黑色绘制。输出不是终端或设置了 NO_COLOR 时，则不使用颜色绘制。
• --png 会把二维码保存为 PNG，而不是直接输出。
• 对于有短链接的上传，显示的是短链接。

示例

$ aktar qr https://files.example.com/2026/10/demo.mp4

$ aktar qr 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 --png cover-qr.png
Saved to cover-qr.png

aktar login

向 Aktar 验证令牌并保存，供其他命令连接时使用。

用法

$ aktar login [--token <token>] [--port <port>]

选项

注意事项

• 在终端中，它会提示输入令牌，并隐藏你输入的内容。通过管道输入时，会从管道读取令牌。
• --token 可以跳过提示，但命令运行期间其他程序能看到令牌，而且令牌会留在 shell 历史记录中，所以 aktar 会对此发出警告。通过管道传入或使用 AKTAR_TOKEN 可以避免这一点。
• 被 Aktar 拒绝的令牌不会保存，退出码为 3。

示例

$ aktar login
Copy the token from Aktar: Settings > Integrations (turn on Allow local connections first).
Token:
Connected to Aktar 0.10.0. Saved to /Users/you/.config/aktar/cli.json

$ pbpaste | aktar login
Connected to Aktar 0.10.0. Saved to /Users/you/.config/aktar/cli.json

$ aktar login --token "$AKTAR_SECRET" --port 47920
aktar: warning: a token on the command line can be seen by other programs (ps) and stays in your shell history. Next time, run aktar login without --token and paste it, or pipe it in.
Connected to Aktar 0.10.0. Saved to /Users/you/.config/aktar/cli.json

aktar logout

删除已保存的令牌和端口。

用法

$ aktar logout

选项

没有选项。

注意事项

• 如果设置了 AKTAR_TOKEN，aktar logout 之后它仍然有效。
• 它不会断开其他客户端。要断开它们，请在 Aktar 中重新生成令牌。

示例

$ aktar logout
Logged out.

$ aktar status
aktar: Not connected to Aktar yet. Run aktar login with the token from Aktar's Settings > Integrations.

aktar status

显示你连接的是哪个 Aktar、使用的端口、Aktar 中选中的上传目标，以及配置文件的位置。

用法

$ aktar status [--json]

选项

注意事项

• 在脚本中快速检查连接的好办法：无法连接 Aktar 或令牌不正确时，退出码为 3。

示例

$ aktar status
Aktar 0.10.0 (build 28) on port 47913
Destination: Screenshots (Cloudflare R2, screenshots)
Config: /Users/you/.config/aktar/cli.json

$ aktar status --json
{
  "app": "Aktar",
  "version": "0.10.0",
  "build": "28",
  "apiVersion": 1,
  "defaultDestinationId": "5D1A9C3E-7B2F-4E61-8A0D-3C9B6F2E1A47",
  "outputFormat": "url",
  "port": 47913
}

aktar destinations

列出你的上传目标及其服务商、存储桶和 ID。* 标出 Aktar 中当前选中的那个。

用法

$ aktar destinations [--json]

选项

注意事项

• -d 可以使用名称或 ID。名称匹配不区分大小写；ID 始终有效，即使改了名也一样。
• --json 会为每个上传目标给出 id、name、provider、providerName、bucket、publicBaseURL 和 isDefault。

示例

$ aktar destinations
* Screenshots  Cloudflare R2  screenshots  5D1A9C3E-7B2F-4E61-8A0D-3C9B6F2E1A47
  Builds  Amazon S3  acme-builds  A83F2C10-6D4B-4F7E-9C1A-2B5E8D0F3C66
  Blog  Backblaze B2  blog-assets  E2C7B9A4-1F3D-4A8E-B6C0-9D5F2A7E4B13

$ aktar destinations --json | jq -r '.[] | select(.isDefault) | .name'
Screenshots

aktar history

按从新到旧列出最近的上传：日期、文件名和链接。history 后面的词会用来搜索上传记录。

用法

$ aktar history [search] [options]

选项

注意事项

• 默认列出 20 条，可用 -n 修改。
• --json 给出的字段与 aktar upload --json 相同，包括每个上传的 id，可用于 aktar qr。

示例

$ aktar history -n 3
2026-10-01  screenshot.png  https://files.example.com/2026/10/7f3c2a91.png
2026-10-01  cover.jpg  https://files.example.com/blog/2026/cover.jpg
2026-09-30  invoice-september.pdf  https://files.example.com/2026/09/0e7d51b3.pdf

$ aktar history invoice -d Screenshots
2026-09-30  invoice-september.pdf  https://files.example.com/2026/09/0e7d51b3.pdf
2026-08-29  invoice-august.pdf  https://files.example.com/2026/08/a6c94f20.pdf

$ aktar history -d Builds -n 1 --json | jq -r '.[0].url'
https://acme-builds.s3.amazonaws.com/2026/10/app-3f9c2e1.zip

aktar mcp

运行 Model Context Protocol (MCP) 服务器，让 Claude、Cursor、VS Code、Codex 等 AI 智能体可以通过 Aktar 上传文件、查找过往上传并生成链接。只需在智能体中添加一次，需要时由智能体自动启动。

用法

$ aktar mcp [--root <folder>]... [--read-only | --allow-replace | --allow-delete] [--max-link-minutes <n>] [--log <file>]

选项

注意事项

• 请先运行 aktar login。服务器每次调用都会读取已保存的令牌，所以重新登录后无需重启智能体。
• 上传会公开文件：任何拿到链接的人都能打开。除非你允许，否则智能体在调用工具前会先询问。
• 只会从你用 --root 指定的文件夹上传文件，未指定时只从服务器运行所在的文件夹上传。如果那是你的主文件夹或磁盘根目录（有些应用就是这样），在你添加 --root 之前不会上传任何本地文件。如果你确实需要，--root ~ 会允许整个主文件夹。路径会先解析（包括符号链接）再检查。
• 无论放在哪里，机密文件都不会被上传：SSH 密钥和私钥、.env 文件、云服务和包管理器的凭据（~/.aws、~/.kube、~/.npmrc 等）、Aktar 自己的配置、钥匙串、浏览器配置文件和密码数据库。有多个硬链接的文件也会被拒绝。要分享这类文件，请自己用 aktar upload 上传。
• --read-only 只提供不会改动存储桶内容的工具。replace_file 会像删除一样覆盖文件，所以只有使用 --allow-replace 时才提供；delete_upload 只有使用 --allow-delete 时才提供（它同时也会提供 replace_file）。
• create_temporary_link 生成的链接最长有效 60 分钟，除非 --max-link-minutes 允许更长。指定 --root 时不提供 upload_clipboard，因为剪贴板里可能是任何内容。
• 工具结果开头会注明：其中的文件名、键和消息都是数据，而不是指令。--log 会记录每一次调用。它最多同时运行 4 个工具调用。
• 如果没有全局安装，请使用 npx -y @getaktar/cli mcp --root ~/Projects 作为命令。
• 通过 stdio 支持当前的 MCP 版本（2026-07-28），以及以 initialize 开头的早期版本（2024-11-05 至 2025-11-25）。需要 aktar 0.4.0；上述限制自 aktar 0.6.0 起提供。

工具

示例

$ claude mcp add aktar -- aktar mcp --root ~/Projects
$ codex mcp add aktar -- aktar mcp --root ~/Projects

$ claude mcp add aktar -- aktar mcp --root ~/Projects --root ~/Desktop --allow-replace

$ claude mcp add aktar -- aktar mcp --root ~/Projects --log ~/aktar-mcp.log

aktar skill

输出一份智能体技能（SKILL.md），教智能体使用带 --json 的 aktar 命令：该运行什么、如何读取结果，以及只上传你要求分享的内容。适用于支持技能但不支持 MCP 的智能体。

用法

$ aktar skill

选项

没有选项。

注意事项

• 把它保存到智能体查找技能的位置，例如 Claude Code 的 ~/.claude/skills/aktar/。

示例

$ mkdir -p ~/.claude/skills/aktar
$ aktar skill > ~/.claude/skills/aktar/SKILL.md

所有命令通用的选项