Aktar

Aktar CLI

在终端中将文件上传到自己的 S3、Cloudflare R2 或 Backblaze B2 存储桶，并获取链接。

aktar 命令会连接你 Mac 或 Windows PC 上的 Aktar 应用，因此会使用你已在其中设置的目标位置、密钥、路径模板和链接设置。你的存储密钥不会离开该应用。

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

安装

npm install -g @getaktar/cli
# or
brew install getaktar/tap/aktar-cli

或者无需安装即可运行：npx @getaktar/cli upload file.png。

需要 Node.js 18 或更高版本，以及 Aktar for Mac 0.18.0 或 Aktar for Windows 0.11.0 或更高版本（较早版本的 CLI 可与 Aktar for Mac 0.4.0 及更高版本配合使用）。

连接到 Aktar

1. 在 Aktar 中，打开 Settings > Integrations 并启用 Allow local connections。
2. 复制此处显示的令牌。
3. 运行：

aktar login

并在提示时粘贴令牌（请避免使用 aktar login --token <token>：其他程序可以看到命令行，而且令牌会保留在 shell 历史记录中）。令牌会与 Aktar 核对，并保存到 ~/.config/aktar/cli.json（Windows 上为 %APPDATA%\aktar\cli.json），且仅你本人可读取。你也可以通过管道传入令牌（pbpaste | aktar login），或改为设置 AKTAR_TOKEN（如果更改了端口，也需设置 AKTAR_PORT）。

用法

aktar upload report.pdf                     # prints the link
aktar upload *.png -f markdown              # one Markdown image per file
aktar upload build.zip -d Builds            # pick a destination by name or ID
aktar upload notes.txt --folder docs/2026   # keep the name, upload into a folder
aktar upload IMG_4021.jpg --name cover      # upload as cover.jpg
aktar upload log.txt --expires 7            # delete after 7 days
aktar upload --clipboard                    # the file or image on the clipboard
aktar upload demo.mp4 --qr                  # the link and a QR code to open it on your phone
aktar upload talk.pdf --short               # a short link from the destination's link shortener
aktar upload photo.jpg --json               # full details as JSON

aktar status                                # which Aktar and destination you're connected to
aktar destinations                          # list destinations (* marks the selected one)
aktar history invoice -n 5                  # search recent uploads
aktar replace 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 v2.png  # new file, same link
aktar replace docs/guide.pdf guide.pdf -d Docs  # replace a key in a destination's bucket
aktar qr https://example.com                # a QR code of any link or text
aktar qr 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1  # a QR code of an upload in history
aktar short 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1  # a short link for an upload in history

如果不使用 -d，文件会上传到 Aktar 菜单栏中选定的目标位置。上传的文件会像其他文件一样显示在 Aktar 的历史记录中。

--format 用于选择打印内容：url（默认）、markdown、html 或 custom（你在 Aktar 中设置的模板）。--expires 接受 1、7、14 或 30 天，且目标位置必须启用 Aktar 的自动删除规则；不指定时，文件会保留。

--name 可将单个文件以其他名称上传：目标位置的路径模板中 {filename} 和 {ext} 会使用该名称，Aktar 的历史记录中也会显示该名称。如果名称没有扩展名，则会添加文件自身的扩展名（--name cover 会将 IMG_4021.jpg 上传为 cover.jpg）；如果名称带有扩展名，则会按原样使用。使用 --folder 时，该名称就是文件夹内的文件名。

如果存储桶中已存在相同文件（内容、目标位置和到期时间均相同），Aktar 不会再次上传，而是提供现有链接。aktar 会照常打印链接，并在 stderr 中注明（aktar: photo.jpg: already uploaded, reused the existing link），因此读取 stdout 的脚本仍会为每个文件获取一个链接。此功能需要 Aktar for Mac 0.10.0 或 Windows 0.3.0。

短链接

如果 Aktar 中为某个目标配置了链接缩短服务（Shlink、YOURLS、Kutt、Dub、Short.io 或你自己的服务），Aktar 会按照该目标的规则缩短链接，并由 aktar 输出短链接。--format 也会使用短链接：Markdown、HTML 和自定义格式由 Aktar 生成，其中包含短链接。

• --short 会为本次上传生成短链接，即使目标的“仅缩短长于此长度的链接”规则会跳过它。如果目标没有链接缩短服务，此操作会失败。
• --no-short 表示本次不生成短链接。

如果 Aktar 无法生成短链接（例如，缩短服务不可用），上传仍会继续：aktar 会输出原始链接，并在 stderr 中说明原因（aktar: talk.pdf: couldn't make a short link, printed the original link: ...）。

aktar short <upload-id|link> 会通过上传 ID、链接或短链接查找历史记录中的上传，并为其生成短链接，然后输出该链接。如果该上传已有短链接，则输出已有链接。--json 会输出短链接的详细信息（提供商、状态，以及缩短服务会统计的点击次数），--qr 会附带其二维码。aktar history 会在每个上传的链接后显示其短链接。

较旧版本的 Aktar，以及尚未支持短链接的 Windows 版 Aktar，会忽略 --short 和 --no-short。

二维码

aktar upload --qr 会在每个链接下方输出二维码，方便你用手机打开。无论 --format 输出什么，二维码始终对应链接本身（如果有短链接，则对应短链接）。二维码在终端中始终以黑底白色绘制，不受终端主题影响；如果输出目标不是终端，或设置了 NO_COLOR，则会以无颜色的方式绘制（浅色模块显示为方块），这样手机摄像头无论在浅色还是深色背景下都能读取。--qr 不能与 --json 一起使用。

aktar qr <text> 可显示任意链接或文本的二维码；文本包含空格时请加引号。传入 aktar history --json 输出中的上传 ID 时，它会显示该上传的链接（如果有短链接，则显示短链接）及其二维码。--png <file> 可将二维码另存为 PNG：

aktar qr https://files.example.com/2026/09/7f3c2a91.png --png link.png

Aktar 会为你完成的工作

应用会针对每个目标完成这些工作，因此 CLI 无需额外处理：

• 如果目标已设置，则将图像转换为 WebP 或 AVIF
• 在路径模板中使用 {md5} 和 {sha256}，根据文件内容为文件命名
• 处理大文件：超过 5 GB 时，Aktar 会分块上传，并在连接中断后恢复上传。aktar 会将文件流式传输到应用，因此文件大小不受影响

aktar 输出的链接对应转换后的文件，也就是实际存储的文件。

JSON 输出

aktar upload --json 会输出一个数组，每个上传的文件对应一项：

[
  {
    "id": "0B6C…",
    "filename": "photo.jpg",
    "objectKey": "2026/09/7f3c2a91.jpg",
    "url": "https://files.example.com/2026/09/7f3c2a91.jpg",
    "shortUrl": null,
    "destinationId": "5D1A…",
    "destinationName": "Screenshots",
    "mimeType": "image/jpeg",
    "size": 482113,
    "createdAt": "2026-09-30T12:00:00Z",
    "expiresAt": null,
    "formats": { "url": "…", "markdown": "…", "html": "…", "custom": "…" },
    "reused": false
  }
]

如果文件已经存在，因此没有上传任何内容，reused 的值为 true；较旧版本的 Aktar 不会输出此字段。shortUrl 是该上传的短链接；如果没有，则为 null；formats 已使用短链接。如果 Aktar 无法生成短链接，shortLinkError 会说明原因。aktar history --json 也包含 shortUrl。

退出代码

代码	含义
0	所有操作均成功
1	至少有一次上传或请求失败（其他操作仍会继续）
2	参数错误，或文件不存在（没有上传任何内容）
3	未登录、Aktar 未运行、本地 API 已关闭、令牌错误，或该端口上的应用无法证明自己是 Aktar（或版本过旧，无法证明）

AI Agent（MCP 和技能）

MCP 服务

aktar mcp 会运行一个 Model Context Protocol 服务，让 Claude、Cursor、VS Code、Codex 和其他 Agent 可以通过 Aktar 上传文件、查找过去的上传记录并创建链接。先连接 Aktar（aktar login），然后将其添加到你的 Agent，并指定它可以从中上传文件的文件夹：

claude mcp add aktar -- aktar mcp --root ~/Projects    # Claude Code
codex mcp add aktar -- aktar mcp --root ~/Projects     # Codex

适用于 Claude Desktop、Cursor、VS Code 和其他采用 JSON 配置的应用：

{
  "mcpServers": {
    "aktar": { "command": "aktar", "args": ["mcp", "--root", "/Users/you/Projects"] }
  }
}

如果不进行全局安装，请使用 "command": "npx", "args": ["-y", "@getaktar/cli", "mcp", "--root", "/Users/you/Projects"]。

工具	功能
upload_file	上传文件（可选设置目标位置、名称、文件夹、过期时间和短链接），并返回其链接、Markdown 和 HTML
upload_clipboard	上传剪贴板中的内容（使用 --root 时不会提供此工具）
replace_file	将新文件写入已有上传文件或存储桶中的任意文件，同时保留其链接（仅使用 --allow-replace 或 --allow-delete 时提供；Mac 0.14.0 / Windows 0.7.0）
create_short_link	根据上传文件目标位置的链接缩短服务创建短链接
search_uploads	搜索上传历史记录（包含每个上传文件的短链接）
list_destinations	列出目标位置及各自适用的文件类型
list_bucket	浏览存储桶中的文件夹和文件
create_temporary_link	创建一段时间后失效的链接（预签名 URL）。这会授予访问权限：在链接过期前，任何持有链接的人都可以下载文件，即使文件位于私有存储桶中也是如此。除非 --max-link-minutes 允许更长时间，否则最长为 60 分钟
get_thumbnail	获取上传文件的预览图（Mac 0.13.0 / Windows 0.6.0）
list_watched_folders	列出受监控的文件夹及其状态
get_status	检查连接状态
delete_upload	从存储桶中删除上传文件（仅使用 --allow-delete 时提供）

上传会公开文件，因此请留意 Agent 发送的内容。除非你允许，否则 Agent 会在调用工具前征求许可；此外，服务也会限制其可访问的内容：

• --root <folder>：仅允许从此文件夹上传文件（可重复指定多个）。检查前会解析路径，包括符号链接。不使用 --root 时，只能从服务运行所在的文件夹上传文件（Agent 通常会在你的项目目录中启动服务）。如果某些应用将服务运行在你的主目录或磁盘根目录下，则在添加 --root 前，不会上传任何本地文件。--root ~ 或 --root / 会允许访问更多内容，请谨慎使用。
• 无论密钥位于何处，都绝不会上传：SSH 和私钥（id_rsa、id_ed25519、*.pem、*.p12、*.pfx……）、.env 文件、~/.ssh、~/.gnupg、~/.aws、~/.azure、~/.config/gcloud、~/.kube、~/.docker、~/.netrc、~/.npmrc、~/.pypirc、~/.git-credentials、Aktar 自身的配置、钥匙串、浏览器配置文件和密码数据库（*.kdbx）。包含多个硬链接的文件也不会上传。如需分享这些内容，请使用 aktar upload 手动上传。
• --read-only：仅提供不会更改存储桶内容的工具（搜索、列出内容、创建临时链接和缩略图）。
• --allow-replace：同时提供 replace_file，用于覆盖存储桶中的文件。默认不提供此工具，因为旧内容会丢失，就像删除操作一样。
• --allow-delete：同时提供 delete_upload（以及 replace_file）。
• --max-link-minutes <n>：允许 create_temporary_link 创建最长可用 n 分钟的链接（默认 60 分钟，最长 10080 分钟，即 7 天）。
• --log <file>：将每次工具调用（时间、工具、参数、结果）追加到只有你能读取的文件中，以便之后查看 Agent 做了什么。

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

工具结果开头会附带一条说明，指出其中的文件名、密钥和消息来自文件及存储桶，因此 Agent 应将其视为数据，而非指令；其中的控制字符和文本方向字符会被移除。

此服务同时支持当前的逐请求协议（2026-07-28）和较早的 initialize 版本（2024-11-05 至 2025-11-25）。

Agent 技能

使用 skills 但不使用 MCP 的 Agent 可以直接使用 CLI。aktar skill 会输出一份 SKILL.md，指导它们如何操作：

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

验证 Aktar

发送令牌前，aktar 会要求端口上的应用证明它持有相同的令牌（但不会发送令牌），因此，如果 Aktar 未运行，而另一个程序正在监听其端口，该程序也无法获取令牌或你的文件。此功能需要 Aktar for Mac 0.18.0 或 Aktar for Windows 0.11.0 及更高版本；如果 Aktar 版本较旧，aktar 会停止运行并提示你更新。

Typora

在 Typora 中，打开 设置 > 图像 > 图像上传，选择 自定义命令 并输入：

aktar upload

Typora 会传入图像路径，并逐行读取链接。点击 测试上传器 进行检查。

链接

• 网站：https://getaktar.com/cli/
• Aktar for Mac and Windows：https://getaktar.com
• Homebrew：brew install getaktar/tap/aktar-cli

许可证

MIT