aktar CLI 說明文件：指令、選項、JSON 與實用範例

Q: Aktar isn't running, or its local API is turned off

打開 Aktar，確認設定 > 整合中的允許本機連線已開啟。如果你在那裡改過連接埠，請用 --port 或 AKTAR_PORT 傳入，或重新執行 aktar login --port。結束代碼 3。

Q: Not connected to Aktar yet

沒有已儲存的權杖，也沒有設定 AKTAR_TOKEN。請用 Aktar 設定 > 整合中的權杖執行 aktar login。結束代碼 3。

Q: The token doesn't match Aktar's anymore

權杖已在 Aktar 中重新產生，或是打錯了。請用目前的權杖重新執行 aktar login。如果設定了 AKTAR_TOKEN，它的優先順序高於已儲存的權杖，所以也要更新或取消設定它。結束代碼 3。

Q: Auto-delete isn't set up for this destination

--expires 需要儲存貯體的自動刪除規則。請從 Aktar 選單列或目的地設定中的刪除時間設定一次，或是不加 --expires 上傳。結束代碼 1。

Q: No destination named "…"

訊息會列出 Aktar 中現有的名稱。請檢查拼字，含空格的名稱要加上引號（-d "Client work"），或使用 aktar destinations 顯示的 ID。結束代碼 2。

Q: 大型檔案上傳很久

這取決於儲存服務供應商的速度：aktar 對上傳沒有時間限制，並會在終端機的 stderr 顯示進度。完成之前請讓 Aktar 保持執行。如果連線中斷或 Aktar 結束（Aktar closed the connection before the request finished），再上傳一次同一個檔案即可：Aktar for Mac 0.10.0 和 Windows 0.3.0 會從最後一個分段繼續。

Q: aktar 無法啟動：SyntaxError 或 parseArgs

你的 Node.js 版本低於 18。用 node --version 檢查並更新，或改用 Homebrew 安裝 aktar，它會自帶 Node.js。

Q: PowerShell 顯示已停用指令碼執行

PowerShell 的執行原則封鎖了 npm 為 aktar 安裝的指令碼。請改為執行 aktar.cmd，或用 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 一次允許本機指令碼。

總覽

aktar 是同一台電腦上 Aktar App 的遙控器。你把檔案交給它，它透過 127.0.0.1 轉交給 Aktar，再由 Aktar 依照你已設定好的目的地、金鑰、路徑範本和連結設定上傳。連結會回到你的終端機。

它是什麼

一個小巧的 Node.js 指令，適合用在腳本、在你自己的 Mac 或 Windows 電腦上執行的 CI 工作，以及 Typora 這類編輯器
可以上傳檔案和剪貼簿內容、顯示 QR Code，並讀取你的目的地和上傳歷史記錄
和 App 一樣免費且開放原始碼（MIT）

它不是什麼

無法單獨運作：Aktar 沒有執行時，它什麼都上傳不了。它從不保存你的儲存空間金鑰
不適用於 Linux 伺服器或遠端機器：它只和同一台電腦上的 Aktar 溝通。在那些環境中，請使用儲存服務供應商自己的 CLI

系統需求

Aktar for Mac 0.4.0 或以上版本，或 Aktar for Windows，並至少設定一個目的地
Node.js 18 或以上版本（使用 Homebrew 時會自動幫你安裝）
--name、--qr 和 aktar qr 需要 aktar 0.2.0 或以上版本
沿用已上傳檔案的連結需要 aktar 0.2.0，以及 Aktar for Mac 0.10.0 或 Aktar for Windows 0.3.0
aktar replace 需要 aktar 0.3.0，以及 Aktar for Mac 0.14.0 或 Aktar for Windows 0.7.0 或以上版本

安裝

用 npm 或 Homebrew 安裝一次就好。兩種方式都會把 aktar 指令加到你的 PATH。

使用 npm（macOS 和 Windows）

$ npm install -g @getaktar/cli

使用 Homebrew（macOS）

$ brew install getaktar/tap/aktar-cli

或是不安裝，直接執行一次：

$ npx @getaktar/cli upload file.png

查看目前的版本：

$ aktar --version
0.3.0

連接 Aktar

在 Mac 或 Windows 版 Aktar 中打開設定 > 整合，開啟允許本機連線。之後 Aktar 只會在 127.0.0.1 上監聽，連接埠預設為 47913，也可以在那裡修改。
複製下方顯示的權杖。
執行 aktar login，在 Token: 提示處貼上權杖。輸入時不會顯示內容，而且儲存前會先向 Aktar 驗證，打錯的權杖不會被存下來。

$ 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

權杖存放在哪裡

aktar login 會把權杖和連接埠存到 Mac 上的 ~/.config/aktar/cli.json（若有設定 XDG_CONFIG_HOME，則為 $XDG_CONFIG_HOME/aktar/cli.json），以及 Windows 上的 %APPDATA%\aktar\cli.json。只有你的使用者帳號可以讀取。

cli.json

{
  "token": "…",
  "port": 47913
}

aktar logout 會刪除這個檔案。若要一次斷開所有用戶端，請在 Aktar 中按一下權杖旁的重新產生，再用新的權杖重新執行 aktar login。

腳本與 CI

在建置機器上可以略過 aktar login，改為設定 AKTAR_TOKEN（如果改過連接埠，也要設定 AKTAR_PORT）。它們的優先順序高於已儲存的檔案。Aktar 必須在那台機器上執行，並登入同一個使用者工作階段。

$ AKTAR_TOKEN="$AKTAR_SECRET" aktar upload dist/app.zip -d Builds

變數	用途
`AKTAR_TOKEN`	Aktar 設定 > 整合中的權杖。會取代已儲存的權杖使用。
`AKTAR_PORT`	Aktar 本機 API 的連接埠（如果你改過）。`--port` 的優先順序高於它。
`NO_COLOR`	用一般字元而不是終端機顏色繪製 QR Code。
`XDG_CONFIG_HOME`	macOS 上設定資料夾的位置（預設為 `~/.config`）。Windows 上使用 `%APPDATA%`。

指令

除了搭配純文字或連結使用的 aktar qr，所有指令都要和 Aktar 溝通。不加 -d 時，檔案會上傳到 Aktar 選單列中選取的目的地，並和其他上傳項目一樣出現在 Aktar 的歷史記錄中。aktar --help 也會列出同樣的清單。在 Aktar for Mac 0.14.0 或 Aktar for Windows 0.7.0 以上版本中，不加 -d 的上傳會先依照目的地的用於規則，所以影像可以送到截圖用的目的地，建置檔則送到另一個。

aktar upload
aktar upload --clipboard
aktar replace
aktar qr
aktar login
aktar logout
aktar status
aktar destinations
aktar history

`aktar upload`

上傳一個或多個檔案，每個檔案完成時依序輸出一個連結。

用法

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

選項

旗標	值	說明
`-d, --destination`	`<name\|id>`	要上傳到的目的地，以名稱或 ID 指定。預設為 Aktar 中選取的目的地。
`-f, --format`	`<format>`	要輸出的內容：`url`（預設）、`markdown`、`html` 或 `custom`（你在 Aktar 中的範本）。
`--name`	`<name>`	以這個名稱上傳單一檔案。名稱沒有副檔名時，會保留原本的副檔名。
`--folder`	`<path>`	保留檔名，上傳到這個資料夾。
`--expires`	`<days>`	讓儲存貯體在 1、7、14 或 30 天後刪除檔案。0 代表保留。
`--qr`		同時為每個連結輸出 QR Code。
`--json`		輸出包含每個上傳項目完整資訊的 JSON 陣列，而不是連結。
`--port`	`<port>`	Aktar 本機 API 的連接埠，只對這次的指令有效。優先順序高於 `AKTAR_PORT` 和已儲存的連接埠。

注意事項

上傳前會先檢查所有檔案：只要有一個不存在，就不會上傳任何檔案，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 upload screenshot.png
https://files.example.com/2026/10/7f3c2a91.png

多個檔案，輸出成 Markdown：依序每個檔案一行。

$ 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

同一個檔案已經在儲存貯體中：連結照常輸出，提示訊息則輸出到 stderr。

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

`aktar upload --clipboard`

上傳剪貼簿中的檔案或影像，效果和 Aktar 本身的剪貼簿快速鍵一樣。

用法

$ aktar upload --clipboard [options]

選項

旗標	值	說明
`--clipboard`		上傳剪貼簿中的內容，而不是檔案。
`-d, --destination`	`<name\|id>`	要上傳到的目的地，以名稱或 ID 指定。預設為 Aktar 中選取的目的地。
`-f, --format`	`<format>`	要輸出的內容：`url`（預設）、`markdown`、`html` 或 `custom`（你在 Aktar 中的範本）。
`--expires`	`<days>`	讓儲存貯體在 1、7、14 或 30 天後刪除檔案。0 代表保留。
`--qr`		同時為每個連結輸出 QR Code。
`--json`		輸出包含每個上傳項目完整資訊的 JSON 陣列，而不是連結。
`--port`	`<port>`	Aktar 本機 API 的連接埠，只對這次的指令有效。優先順序高於 `AKTAR_PORT` 和已儲存的連接埠。

注意事項

傳入檔案或 --clipboard，兩者只能擇一。
--name 和 --folder 只能用於檔案。-d、-f、--expires、--qr 和 --json 的用法和上傳檔案時相同。
使用 --json 時，仍會輸出陣列，裡面只有一筆。

範例

剛剛複製的截圖。

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

以 Markdown 格式，上傳到名為 Blog 的目的地。

$ 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]

選項

旗標	值	說明
`-d, --destination`	`<name\|id>`	用於物件鍵：它所在儲存貯體的目的地，以名稱或 ID 指定。預設為 Aktar 中選取的目的地。
`-f, --format`	`<format>`	要輸出的內容：`url`（預設）、`markdown`、`html` 或 `custom`（你在 Aktar 中的範本）。
`--qr`		同時為每個連結輸出 QR Code。
`--json`		輸出包含每個上傳項目完整資訊的 JSON 陣列，而不是連結。
`--port`	`<port>`	Aktar 本機 API 的連接埠，只對這次的指令有效。優先順序高於 `AKTAR_PORT` 和已儲存的連接埠。

注意事項

第一個引數是 aktar history 中的上傳 ID 或連結（Aktar 的歷史記錄項目會跟著更新），否則就是 -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 或以上版本。

範例

以 ID 取代歷史記錄中的上傳項目，連結維持不變。

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

取代另一個目的地儲存貯體中的物件鍵，並以 Markdown 輸出。

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

`aktar qr`

在終端機中顯示連結或任何文字的 QR Code，方便在手機上打開。傳入上傳 ID 時，會顯示該上傳項目的連結和它的 QR Code。

用法

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

選項

旗標	值	說明
`--png`	`<file>`	把 QR Code 儲存成 PNG 檔案，而不是直接輸出。
`--port`	`<port>`	Aktar 本機 API 的連接埠，只對這次的指令有效。優先順序高於 `AKTAR_PORT` 和已儲存的連接埠。

注意事項

只能傳入一個引數，含空格的文字請加上引號。
上傳 ID 就是 aktar history --json 或 aktar upload --json 輸出中的 id。aktar 會在 Aktar 歷史記錄的最近 1,000 個上傳項目中尋找；如果是純文字或連結，則完全不需要 Aktar。
不論終端機使用什麼主題，QR Code 都會以白底黑色繪製。輸出不是終端機，或設定了 NO_COLOR 時，則不使用顏色繪製。
--png 會把 QR Code 儲存成 PNG，而不是直接輸出。

範例

任何連結的 QR Code，用手機相機掃描就能打開。

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

歷史記錄中的上傳項目，儲存成 PNG。

$ 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`	`<token>`	直接提供權杖，不顯示提示。
`--port`	`<port>`	Aktar 的連接埠，會和權杖一起儲存。預設為 47913。

注意事項

在終端機中，它會要求輸入權杖，並隱藏你輸入的內容。輸入來自管道時，會從管道讀取權杖。
--token 可以略過提示，但權杖會留在 shell 的歷史記錄中。透過管道傳入或使用 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

在 Mac 上，使用從 Aktar 複製的權杖。

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

不顯示提示，並指定改過的連接埠。

$ aktar login --token "$AKTAR_SECRET" --port 47920
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.

之後，指令會要求你重新登入（結束代碼 3）。

$ 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]

選項

旗標	值	說明
`--json`		輸出 JSON 而不是文字。
`--port`	`<port>`	Aktar 本機 API 的連接埠，只對這次的指令有效。優先順序高於 `AKTAR_PORT` 和已儲存的連接埠。

注意事項

在腳本中快速檢查連線的好方法：無法連上 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

同樣的資訊以 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]

選項

旗標	值	說明
`--json`		輸出 JSON 而不是文字。
`--port`	`<port>`	Aktar 本機 API 的連接埠，只對這次的指令有效。優先順序高於 `AKTAR_PORT` 和已儲存的連接埠。

注意事項

-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

用 jq 取出選取的目的地名稱。

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

`aktar history`

由新到舊列出最近的上傳項目：日期、檔名和連結。history 後面的字詞會用來搜尋歷史記錄。

用法

$ aktar history [search] [options]

選項

旗標	值	說明
`-n, --limit`	`<n>`	要列出幾個上傳項目。預設為 20。
`-d, --destination`	`<name\|id>`	只列出上傳到這個目的地的項目，以名稱或 ID 指定。
`--json`		輸出 JSON 而不是文字。
`--port`	`<port>`	Aktar 本機 API 的連接埠，只對這次的指令有效。優先順序高於 `AKTAR_PORT` 和已儲存的連接埠。

注意事項

預設列出 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

用 jq 取出最新建置檔的連結。

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

所有指令通用的選項

旗標	值	說明
`-h, --help`		顯示指令和選項清單。
`-v, --version`		顯示 `aktar` 的版本。
`--port`	`<port>`	Aktar 本機 API 的連接埠，只對這次的指令有效。優先順序高於 `AKTAR_PORT` 和已儲存的連接埠。

輸出

格式

-f 決定每個上傳項目要輸出什麼。不加時，不論 Aktar 選單列複製的是哪種格式，aktar 都會輸出純 URL。Markdown 和 HTML 會嵌入影像，其他檔案則輸出連結，和 Aktar 的做法一樣。

格式	photo.jpg 的輸出
`-f url`	`https://files.example.com/2026/10/7f3c2a91.jpg`連結（預設）。
`-f markdown`	`![](https://files.example.com/2026/10/7f3c2a91.jpg)`Markdown 影像；其他檔案則為 Markdown 連結。
`-f html`	`<img src="https://files.example.com/2026/10/7f3c2a91.jpg" alt=""><img>` 標籤；其他檔案則為 `<a>` 連結。
`-f custom`	`![photo.jpg](https://files.example.com/2026/10/7f3c2a91.jpg)`你在 Aktar 設定中的範本，會填入 `{url}`、`{filename}` 和其他變數。

stdout 與 stderr

標準輸出只會收到連結，每行一個，順序和檔案相同（使用 --qr 時還有 QR Code）。其他內容都輸出到標準錯誤：進度、錯誤，以及像 aktar: photo.jpg: already uploaded, reused the existing link 這樣的提示。因此 url=$(aktar upload file) 和 aktar upload *.png > links.txt 永遠只會拿到乾淨的連結。

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

JSON

--json 會在所有檔案都完成後輸出一個陣列，每個上傳的檔案一筆。上傳失敗的檔案不會列入（它們會回報到 stderr），所以也要檢查結束代碼。

$ aktar upload photo.jpg --json
[
  {
    "id": "0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1",
    "filename": "photo.jpg",
    "objectKey": "2026/10/7f3c2a91.jpg",
    "url": "https://files.example.com/2026/10/7f3c2a91.jpg",
    "destinationId": "5D1A9C3E-7B2F-4E61-8A0D-3C9B6F2E1A47",
    "destinationName": "Screenshots",
    "mimeType": "image/jpeg",
    "size": 482113,
    "createdAt": "2026-10-01T12:00:00Z",
    "expiresAt": null,
    "formats": {
      "url": "https://files.example.com/2026/10/7f3c2a91.jpg",
      "markdown": "![](https://files.example.com/2026/10/7f3c2a91.jpg)",
      "html": "<img src=\"https://files.example.com/2026/10/7f3c2a91.jpg\" alt=\"\">",
      "custom": "![photo.jpg](https://files.example.com/2026/10/7f3c2a91.jpg)"
    },
    "reused": false
  }
]

欄位	意義
`id`	這個上傳項目在 Aktar 歷史記錄中的 ID，可傳給 `aktar qr`。
`filename`	Aktar 記錄的檔名：檔案本身的名稱，或 `--name` 指定的名稱。
`objectKey`	檔案在儲存貯體中的位置。
`url`	連結。
`destinationId`	目的地的 ID。
`destinationName`	目的地的名稱。
`mimeType`	檔案類型，以 Aktar 轉換後的結果為準。
`size`	儲存後的大小，單位為位元組。
`createdAt`	上傳時間（ISO 8601，UTC）。
`expiresAt`	儲存貯體刪除它的時間；如果會保留，則為 `null`。
`replacedAt`	檔案最後一次被取代的時間（ISO 8601，UTC）。在被取代之前不會出現，Mac 0.14.0 和 Windows 0.7.0 之前的 Aktar 版本也不會提供。
`formats`	四種格式的連結：`url`、`markdown`、`html` 和 `custom`。
`reused`	因為同一個檔案已經存在而沒有上傳任何東西時為 `true`。Mac 0.10.0 和 Windows 0.3.0 之前的 Aktar 版本不會提供。

結束代碼

代碼	意義
`0`	一切順利。
`1`	至少有一個上傳或請求失敗，其他的仍已完成。Aktar 本身的錯誤（例如尚未設定自動刪除）也屬於這一類。
`2`	引數錯誤、檔案不存在，或 Aktar 中沒有這個名稱的目的地。沒有上傳任何檔案。
`3`	尚未登入、Aktar 沒有執行、本機 API 已關閉，或權杖錯誤。

實用範例

複製、改一下檔名，就完成了。每個範例都只用到上面說明過的功能。

把連結存進變數

只有連結會進入標準輸出，所以指令替換拿到的正好就是 URL。上傳失敗時，|| exit 1 會停止腳本。

url=$(aktar upload build/report.pdf) || exit 1
echo "Report: $url"
Report: https://files.example.com/2026/10/0e7d51b3.pdf

上傳建置檔並發布連結

把建置檔壓縮成 zip，以 commit 的短雜湊值為名上傳到名為 Builds 的目的地，再把連結發送到任何接受 JSON 的 webhook（聊天頻道、問題追蹤系統或你自己的端點）。上傳失敗時，set -e 會在發送前停止。

#!/bin/sh
set -e
zip -qr app.zip dist
url=$(aktar upload app.zip -d Builds --name "app-$(git rev-parse --short HEAD)")
curl -fsS -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d "{\"text\": \"New build: $url\"}"

Makefile 目標

make share 會以今天的日期為名上傳報告，並把連結存在 .last-link。在 Makefile 中，$$ 會把 $ 傳給 shell，而指令行要以 Tab 字元開頭。

Makefile

share: dist/report.pdf
	aktar upload dist/report.pdf --name "report-$$(date +%F)" | tee .last-link

Typora 影像上傳工具

在 Typora 中打開Settings > Image（影像），把影像上傳工具設為Custom Command（自訂指令），並輸入 aktar 的完整路徑（也就是 which aktar 輸出的路徑），後面加上 upload。Typora 會傳入影像路徑，並逐行讀取連結。

/opt/homebrew/bin/aktar upload

包含When Insert…（插入影像時）設定的詳細步驟：把 Typora 影像上傳到 S3。

從 Finder 或「捷徑」上傳

在 Mac 上，於「捷徑」或在 Finder 中接收檔案的 Automator 快速動作裡加入執行 Shell 工序指令（Run Shell Script）動作，並把輸入設為作為引數傳遞。「捷徑」和 Automator 不會載入你 shell 的 PATH，所以需要第一行。選取檔案、執行，連結就會出現在剪貼簿上。

export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
aktar upload "$@" | pbcopy
osascript -e 'display notification "Link copied" with title "aktar"'

它上傳的是檔案，不是資料夾。選取多個檔案會得到多個連結，每行一個。

暫時檔案

記錄檔、螢幕錄影或任何不該留著的檔案，都可以交給儲存貯體刪除。目的地需要先設定 Aktar 的自動刪除規則：從 Aktar 選單列或目的地設定中的刪除時間設定一次即可。

aktar upload crash.log --expires 1
aktar upload screen-recording.mov --expires 7 --qr

會到期的檔案放在儲存貯體中的 tmp/1d/、tmp/7d/ 等位置下，即使 Aktar 沒有執行，儲存貯體也會刪除它們。

在手機上打開連結

--qr 會在連結下方輸出 QR Code，用手機相機對準終端機即可。之後想再次顯示，把上傳項目的 ID 傳給 aktar qr，這裡用的是符合「demo」的最新上傳項目。

aktar upload demo.mp4 --qr
aktar qr "$(aktar history demo -n 1 --json | jq -r '.[0].id')"

Windows PowerShell

同樣的做法也適用於 PowerShell。$LASTEXITCODE 存放結束代碼，ConvertFrom-Json 可以讀取 --json 的輸出。

PowerShell

$url = aktar upload .\dist\app.zip -d Builds
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Set-Clipboard $url

$upload = aktar upload .\report.pdf --json | Out-String | ConvertFrom-Json
$upload.formats.markdown

Aktar 幫你處理的事

CLI 只負責轉交檔案，其餘都由 Aktar 依照每個目的地的設定處理。所以你在 App 中設定的一切，同樣適用於 aktar upload，不需要任何額外選項，而你拿到的連結就是最終儲存檔案的連結。

路徑範本
目的地的物件路徑決定檔名，可使用 {year}、{uuid}、{filename} 等變數。{md5} 和 {sha256} 會依檔案內容命名。
影像處理
如果目的地會把影像轉換成 WebP 或 AVIF、壓縮或調整尺寸，透過 CLI 上傳的影像也會經過同樣的處理，連結指向轉換後的檔案。
照片後設資料
目的地上傳預設值中的影像後設資料會在照片離開你的電腦之前，移除位置資訊或全部後設資料。
同樣的檔案，同樣的連結
開啟重複的檔案沿用連結後，同一個目的地中內容相同的檔案會直接拿到現有的連結，不會再上傳一次。aktar 會在 stderr 上註明。
大型檔案
大型檔案會分段上傳，沒有 5 GB 的上限，連線中斷後會重試，並從中斷的地方繼續。aktar 以串流方式把檔案傳給 Aktar，所以從不把整個檔案載入記憶體。
公開連結或暫時連結
連結是公開連結，還是也適用於私人儲存貯體的暫時（預先簽署）連結，和在 App 中一樣由目的地決定。

重複檔案沿用連結、影像處理、{md5} 和 {sha256}，以及分段上傳，都是隨 Aktar for Mac 0.10.0 和 Windows 0.3.0 推出：0.10.0 的新功能。

疑難排解

aktar 的錯誤訊息以 aktar: 開頭，並輸出到 stderr。結束代碼會告訴你是哪一類問題。

`Aktar isn't running, or its local API is turned off`

打開 Aktar，確認設定 > 整合中的允許本機連線已開啟。如果你在那裡改過連接埠，請用 --port 或 AKTAR_PORT 傳入，或重新執行 aktar login --port。結束代碼 3。

`Not connected to Aktar yet`

沒有已儲存的權杖，也沒有設定 AKTAR_TOKEN。請用 Aktar 設定 > 整合中的權杖執行 aktar login。結束代碼 3。

`The token doesn't match Aktar's anymore`

權杖已在 Aktar 中重新產生，或是打錯了。請用目前的權杖重新執行 aktar login。如果設定了 AKTAR_TOKEN，它的優先順序高於已儲存的權杖，所以也要更新或取消設定它。結束代碼 3。

`Auto-delete isn't set up for this destination`

--expires 需要儲存貯體的自動刪除規則。請從 Aktar 選單列或目的地設定中的刪除時間設定一次，或是不加 --expires 上傳。結束代碼 1。

`No destination named "…"`

訊息會列出 Aktar 中現有的名稱。請檢查拼字，含空格的名稱要加上引號（-d "Client work"），或使用 aktar destinations 顯示的 ID。結束代碼 2。

大型檔案上傳很久

這取決於儲存服務供應商的速度：aktar 對上傳沒有時間限制，並會在終端機的 stderr 顯示進度。完成之前請讓 Aktar 保持執行。如果連線中斷或 Aktar 結束（Aktar closed the connection before the request finished），再上傳一次同一個檔案即可：Aktar for Mac 0.10.0 和 Windows 0.3.0 會從最後一個分段繼續。

`aktar` 無法啟動：`SyntaxError` 或 `parseArgs`

你的 Node.js 版本低於 18。用 node --version 檢查並更新，或改用 Homebrew 安裝 aktar，它會自帶 Node.js。

PowerShell 顯示已停用指令碼執行

PowerShell 的執行原則封鎖了 npm 為 aktar 安裝的指令碼。請改為執行 aktar.cmd，或用 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 一次允許本機指令碼。

aktar CLI 說明文件

它是什麼

它不是什麼

系統需求

權杖存放在哪裡

腳本與 CI

所有指令通用的選項

格式

stdout 與 stderr

JSON

結束代碼

路徑範本

影像處理

照片後設資料

同樣的檔案，同樣的連結

大型檔案

公開連結或暫時連結

Aktar isn't running, or its local API is turned off

Not connected to Aktar yet

The token doesn't match Aktar's anymore

Auto-delete isn't set up for this destination

No destination named "…"

大型檔案上傳很久

aktar 無法啟動：SyntaxError 或 parseArgs

PowerShell 顯示已停用指令碼執行

`Aktar isn't running, or its local API is turned off`

`Not connected to Aktar yet`

`The token doesn't match Aktar's anymore`

`Auto-delete isn't set up for this destination`

`No destination named "…"`

`aktar` 無法啟動：`SyntaxError` 或 `parseArgs`