• Aktar CLI

Tài liệu aktar CLI

Mọi lệnh, tùy chọn và đầu ra của aktar, kèm ví dụ bạn có thể dán ngay. Mới dùng lần đầu? Tổng quan CLI đọc nhanh hơn.

Tổng quan CLI

Tổng quan

aktar là chiếc điều khiển từ xa cho ứng dụng Aktar trên cùng máy tính. Bạn đưa tệp cho nó, nó chuyển tệp đến Aktar trên 127.0.0.1, và Aktar tải lên bằng các đích, khóa, mẫu đường dẫn và cài đặt liên kết bạn đã thiết lập sẵn. Liên kết được trả về terminal của bạn.

Nó là gì

  • Một lệnh Node.js nhỏ gọn cho script, tác vụ CI trên máy Mac hoặc máy Windows của chính bạn, và các trình soạn thảo như Typora
  • Một cách để tải lên tệp và bộ nhớ tạm, hiển thị mã QR, xem các đích và lịch sử tải lên của bạn
  • Miễn phí và mã nguồn mở (MIT), giống như ứng dụng

Nó không phải là gì

  • Không chạy độc lập: nếu Aktar không chạy, nó không tải lên được gì. Nó không bao giờ giữ khóa lưu trữ của bạn
  • Không dành cho máy chủ Linux hay máy từ xa: nó chỉ nói chuyện với Aktar trên cùng máy tính. Ở đó, hãy dùng CLI của chính nhà cung cấp lưu trữ

Yêu cầu

  • Aktar cho Mac 0.18.0 hoặc Aktar cho Windows 0.11.0 trở lên, với ít nhất một đích. aktar 0.5.0 trở về trước hoạt động với Aktar cho Mac 0.4.0 trở lên
  • Node.js 18 trở lên (Homebrew tự cài cho bạn)
  • --name, --qr và aktar qr cần aktar 0.2.0 trở lên
  • Dùng lại liên kết của tệp đã tải lên cần aktar 0.2.0 và Aktar cho Mac 0.10.0 hoặc Aktar cho Windows 0.3.0
  • aktar replace cần aktar 0.3.0 và Aktar cho Mac 0.14.0 hoặc Aktar cho Windows 0.7.0 trở lên
  • --short, --no-short và aktar short cần aktar 0.5.0 cùng Aktar cho Mac 0.17.0 hoặc Aktar cho Windows 0.10.0, với một dịch vụ rút gọn được thiết lập cho đích

Cài đặt

Cài một lần, bằng npm hoặc Homebrew. Cả hai đều đưa lệnh aktar vào PATH của bạn.

Với npm (macOS và Windows)

npm install -g @getaktar/cli

Với Homebrew (macOS)

brew install getaktar/tap/aktar-cli

Hoặc chạy một lần mà không cần cài gì:

npx @getaktar/cli upload file.png

Kiểm tra phiên bản bạn đang có:

aktar --version
0.6.0

Kết nối với Aktar

  1. Trong Aktar cho Mac hoặc Windows, mở Cài đặt > Tích hợp và bật Cho phép kết nối cục bộ. Khi đó Aktar chỉ lắng nghe trên 127.0.0.1, cổng 47913 trừ khi bạn đổi nó ở đó.
  2. Sao chép token hiển thị bên dưới.
  3. Chạy aktar login và dán token vào lời nhắc Token:. Token được ẩn khi bạn gõ và được kiểm tra với Aktar trước khi lưu, nên token gõ sai sẽ không bị lưu lại.
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

Token được lưu ở đâu

aktar login lưu token và cổng vào ~/.config/aktar/cli.json trên Mac (hoặc $XDG_CONFIG_HOME/aktar/cli.json nếu bạn đã đặt biến này) và vào %APPDATA%\aktar\cli.json trên Windows. Chỉ người dùng của bạn mới đọc được tệp này.

Trước khi gửi token, aktar yêu cầu ứng dụng trên cổng đó chứng minh rằng nó có cùng token, mà không cần gửi token đi. Vì vậy, nếu Aktar không chạy và một chương trình khác đang lắng nghe trên cổng của nó, chương trình đó không nhận được token lẫn tệp của bạn. Điều này cần Aktar cho Mac 0.18.0 hoặc Aktar cho Windows 0.11.0 trở lên; với Aktar cũ hơn, aktar sẽ dừng và yêu cầu bạn cập nhật.

cli.json
{
  "token": "…",
  "port": 47913
}

aktar logout xóa tệp đó. Để chặn mọi client cùng lúc, hãy nhấp Tạo lại cạnh token trong Aktar, rồi chạy lại aktar login với token mới.

Script và CI

Trên máy build, hãy bỏ qua aktar login và đặt AKTAR_TOKEN (cùng AKTAR_PORT nếu bạn đã đổi cổng). Các biến này được ưu tiên hơn tệp đã lưu. Aktar phải đang chạy trên máy đó, trong cùng phiên đăng nhập của người dùng.

AKTAR_TOKEN="$AKTAR_SECRET" aktar upload dist/app.zip -d Builds
BiếnTác dụng
AKTAR_TOKENToken từ Cài đặt > Tích hợp của Aktar. Được dùng thay cho token đã lưu.
AKTAR_PORTCổng API cục bộ của Aktar, nếu bạn đã đổi. --port được ưu tiên hơn.
NO_COLORVẽ mã QR bằng ký tự thường thay vì màu của terminal.
XDG_CONFIG_HOMEVị trí thư mục cấu hình trên macOS (mặc định ~/.config). Trên Windows, %APPDATA% được dùng.

Lệnh

Mọi lệnh đều nói chuyện với Aktar, trừ aktar qr với văn bản thường hoặc một liên kết. Không có -d, tệp được tải lên đích đang chọn trên thanh menu của Aktar và hiện trong lịch sử của Aktar như mọi tệp khác. aktar --help in ra cùng danh sách này. Với Aktar cho Mac 0.14.0 hoặc Aktar cho Windows 0.7.0 trở lên, lượt tải lên không có -d sẽ theo quy tắc Dùng cho của các đích trước, nên ảnh có thể vào đích dành cho ảnh chụp màn hình còn bản build vào đích khác.

aktar upload

Tải lên một hoặc nhiều tệp và in ra mỗi tệp một liên kết, theo đúng thứ tự, ngay khi từng tệp xong.

Cách dùng

aktar upload <file>... [options]

Tùy chọn

CờGiá trịMô tả
-d, --destination<name|id>Đích để tải lên, theo tên hoặc ID. Mặc định: đích đang chọn trong Aktar.
-f, --format<format>Nội dung in ra: url (mặc định), markdown, html hoặc custom (mẫu của bạn trong Aktar).
--name<name>Tải lên một tệp với tên này. Phần mở rộng được giữ nếu tên không có.
--folder<path>Giữ tên tệp và tải lên vào thư mục này.
--expires<days>Để bucket xóa tệp sau 1, 7, 14 hoặc 30 ngày. 0 để giữ tệp.
--shortTạo liên kết ngắn bằng dịch vụ rút gọn của đích, ngay cả khi quy tắc của nó sẽ bỏ qua lần tải lên này.
--no-shortLần này không tạo liên kết ngắn.
--qrIn thêm mã QR cho từng liên kết.
--jsonIn một mảng JSON với đầy đủ chi tiết của từng tệp, thay vì liên kết.
--port<port>Cổng API cục bộ của Aktar, chỉ cho lệnh này. Được ưu tiên hơn AKTAR_PORT và cổng đã lưu.

Cần biết

  • Mọi tệp đều được kiểm tra trước khi tải lên bất cứ thứ gì: nếu một tệp không tồn tại, không tệp nào được tải lên và aktar thoát với mã 2.
  • Nếu một lượt tải lên thất bại, các tệp khác vẫn được tải lên. Mỗi lỗi được báo trên stderr, và mã thoát là 1.
  • Không có --folder, mẫu đường dẫn của đích sẽ đặt tên tệp, giống như khi thả tệp lên thanh menu. Có --folder, tệp giữ nguyên tên bên trong thư mục đó.
  • --name chỉ dùng với một tệp mỗi lần. Dấu gạch chéo bị xóa, và phần mở rộng của tệp được thêm vào nếu tên không có: --name cover tải IMG_4021.jpg lên thành cover.jpg. Với --folder, đó là tên bên trong thư mục.
  • --expires nhận 1, 7, 14 hoặc 30 (ngày), hoặc 0 để giữ tệp. Không có tùy chọn này, tệp được giữ lại, dù Xóa sau trong Aktar được đặt thế nào. Đích cần có quy tắc tự động xóa của Aktar, và không thể kết hợp với --folder.
  • --qr không thể kết hợp với --json, và --png chỉ dùng được với aktar qr.
  • Trong terminal, tiến trình hiển thị trên stderr khi tệp đang tải lên. Tệp được truyền dạng luồng đến Aktar, nên dung lượng không quan trọng, và không có giới hạn thời gian.
  • Nếu đích có dịch vụ rút gọn được thiết lập trong Aktar, liên kết ngắn sẽ được in ra, và --format cùng --qr đều dùng nó. --short tạo liên kết ngắn ngay cả khi quy tắc của đích sẽ bỏ qua lần tải lên này, --no-short thì không tạo. Nếu Aktar không tạo được, liên kết gốc sẽ được in ra và stderr cho biết lý do.

Ví dụ

Một tệp, một liên kết.
aktar upload screenshot.png
https://files.example.com/2026/10/7f3c2a91.png
Nhiều tệp, dạng Markdown: mỗi tệp một dòng, theo thứ tự.
aktar upload *.png -f markdown
![](https://files.example.com/2026/10/1b9e44d0.png)
![](https://files.example.com/2026/10/c2f71a5e.png)
Tải lên với tên khác, vào một thư mục.
aktar upload IMG_4021.jpg --name cover --folder blog/2026
https://files.example.com/blog/2026/cover.jpg
Tệp này đã có sẵn trong bucket: liên kết vẫn được in như thường, còn ghi chú đi vào stderr.
aktar upload photo.jpg
aktar: photo.jpg: already uploaded, reused the existing link
https://files.example.com/2026/09/4d2a8c61.jpg
Khi đích có dịch vụ rút gọn, liên kết ngắn được in ra.
aktar upload talk.pdf --short
https://s.example.com/k3Tq9

aktar upload --clipboard

Tải lên tệp hoặc hình ảnh đang có trong bộ nhớ tạm, giống phím tắt bộ nhớ tạm của chính Aktar.

Cách dùng

aktar upload --clipboard [options]

Tùy chọn

CờGiá trịMô tả
--clipboardTải lên nội dung trong bộ nhớ tạm thay vì tệp.
-d, --destination<name|id>Đích để tải lên, theo tên hoặc ID. Mặc định: đích đang chọn trong Aktar.
-f, --format<format>Nội dung in ra: url (mặc định), markdown, html hoặc custom (mẫu của bạn trong Aktar).
--expires<days>Để bucket xóa tệp sau 1, 7, 14 hoặc 30 ngày. 0 để giữ tệp.
--shortTạo liên kết ngắn bằng dịch vụ rút gọn của đích, ngay cả khi quy tắc của nó sẽ bỏ qua lần tải lên này.
--no-shortLần này không tạo liên kết ngắn.
--qrIn thêm mã QR cho từng liên kết.
--jsonIn một mảng JSON với đầy đủ chi tiết của từng tệp, thay vì liên kết.
--port<port>Cổng API cục bộ của Aktar, chỉ cho lệnh này. Được ưu tiên hơn AKTAR_PORT và cổng đã lưu.

Cần biết

  • Truyền tệp hoặc --clipboard, không truyền cả hai.
  • --name và --folder chỉ dùng với tệp. -d, -f, --expires, --qr và --json hoạt động như với tệp.
  • Với --json, lệnh vẫn in ra một mảng, có một phần tử.

Ví dụ

Ảnh chụp màn hình bạn vừa sao chép.
aktar upload --clipboard
https://files.example.com/2026/10/9a4c03be.png
Dạng Markdown, đến đích tên Blog.
aktar upload --clipboard -f markdown -d Blog
![](https://blog-assets.example.com/2026/10/e5b2c8a4.png)
Bucket xóa tệp sau một ngày.
aktar upload --clipboard --expires 1
https://files.example.com/tmp/1d/2026/10/38f0d7c2.png

aktar replace

Ghi một tệp mới đè lên một tệp đã tải lên, nên khóa và liên kết của nó giữ nguyên. Ai có liên kết cũng sẽ thấy tệp mới.

Cách dùng

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

Tùy chọn

CờGiá trịMô tả
-d, --destination<name|id>Với một khóa: đích có bucket chứa khóa đó, theo tên hoặc ID. Mặc định: đích đang chọn trong Aktar.
-f, --format<format>Nội dung in ra: url (mặc định), markdown, html hoặc custom (mẫu của bạn trong Aktar).
--qrIn thêm mã QR cho từng liên kết.
--jsonIn một mảng JSON với đầy đủ chi tiết của từng tệp, thay vì liên kết.
--port<port>Cổng API cục bộ của Aktar, chỉ cho lệnh này. Được ưu tiên hơn AKTAR_PORT và cổng đã lưu.

Cần biết

  • Đối số đầu tiên là ID tải lên hoặc liên kết từ aktar history (mục lịch sử trong Aktar được cập nhật), nếu không thì là một khóa trong bucket của -d (đích đang chọn trong Aktar khi bỏ trống). Liên kết không có trong lịch sử của Aktar sẽ bị từ chối: hãy truyền khóa của nó kèm -d.
  • Aktar xóa siêu dữ liệu của tệp và đổi kích thước theo cài đặt của đích, nhưng không bao giờ chuyển sang định dạng khác, nên phần mở rộng của khóa giữ nguyên. Tệp trong tmp/{N}d/ bắt đầu đếm lại N ngày.
  • Khóa không bao giờ bị đánh số và không có gì khác được tải lên. --folder, --expires, --name và --clipboard không áp dụng và sẽ bị từ chối.
  • Bản cũ có thể còn trong bộ nhớ đệm của CDN một lúc. Thời gian bộ nhớ đệm ngắn của đích hoặc tính năng xóa bộ nhớ đệm Cloudflare trong Aktar sẽ xử lý việc đó.
  • Cần Aktar cho Mac 0.14.0 hoặc Aktar cho Windows 0.7.0 trở lên.

Ví dụ

Thay thế một tệp trong lịch sử theo ID; liên kết giữ nguyên.
aktar replace 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 report-v2.pdf
https://files.example.com/2026/09/0e7d51b3.pdf
Thay thế một khóa trong bucket của đích khác và in ra dạng Markdown.
aktar replace docs/guide.pdf guide.pdf -d Blog -f markdown
[guide.pdf](https://blog-assets.example.com/docs/guide.pdf)

aktar short

Tạo liên kết ngắn cho một tệp trong lịch sử bằng dịch vụ rút gọn của đích, rồi in ra. Nếu tệp đã có liên kết ngắn, lệnh in liên kết đó.

Cách dùng

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

Tùy chọn

CờGiá trịMô tả
--jsonIn chi tiết liên kết ngắn dưới dạng JSON: nhà cung cấp, trạng thái và lượt nhấp.
--qrIn thêm mã QR của liên kết ngắn.
--port<port>Cổng API cục bộ của Aktar, chỉ cho lệnh này. Được ưu tiên hơn AKTAR_PORT và cổng đã lưu.

Cần biết

  • Truyền ID tệp tải lên hoặc một liên kết từ aktar history; liên kết ngắn của nó cũng được. aktar tìm trong 1.000 tệp tải lên gần nhất.
  • Đích cần có dịch vụ rút gọn trong mục Liên kết ngắn của Aktar: Shlink, YOURLS, Kutt, Dub, Short.io hoặc một yêu cầu tùy chỉnh. Liên kết ngắn do dịch vụ đó tạo, nên liên kết và dữ liệu lượt nhấp vẫn nằm trong hạ tầng của bạn.
  • --json in chi tiết liên kết ngắn: nhà cung cấp, trạng thái, cùng lượt nhấp và lần nhấp cuối nếu dịch vụ có đếm. --qr thêm mã QR của nó. Không thể dùng cả hai cùng lúc.
  • Cần Aktar cho Mac 0.17.0 hoặc Aktar cho Windows 0.10.0. Các phiên bản cũ hơn sẽ trả lời rằng chưa tạo được liên kết ngắn.

Ví dụ

Liên kết ngắn cho một tệp trong lịch sử.
aktar short 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1
https://s.example.com/Qm3xZ

aktar qr

Hiển thị mã QR của một liên kết hoặc văn bản bất kỳ trong terminal, để bạn mở trên điện thoại. Khi nhận ID tải lên, lệnh hiển thị liên kết của tệp đó cùng mã QR.

Cách dùng

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

Tùy chọn

CờGiá trịMô tả
--png<file>Lưu mã QR thành tệp PNG thay vì in ra.
--port<port>Cổng API cục bộ của Aktar, chỉ cho lệnh này. Được ưu tiên hơn AKTAR_PORT và cổng đã lưu.

Cần biết

  • Truyền đúng một đối số, và đặt văn bản có dấu cách trong dấu ngoặc kép.
  • ID tải lên là id từ aktar history --json hoặc aktar upload --json. aktar tìm nó trong 1.000 lượt tải lên gần nhất trong lịch sử của Aktar; với văn bản thường hoặc liên kết, nó không cần Aktar.
  • Mã được vẽ màu đen trên nền trắng trong terminal, bất kể giao diện của terminal. Khi đầu ra không phải terminal, hoặc khi NO_COLOR được đặt, mã được vẽ không màu.
  • --png lưu mã QR thành tệp PNG thay vì in ra.
  • Với tệp có liên kết ngắn, lệnh hiển thị liên kết ngắn.

Ví dụ

Mã QR cho liên kết bất kỳ. Camera điện thoại sẽ mở nó.
aktar qr https://files.example.com/2026/10/demo.mp4
Một tệp trong lịch sử, lưu thành PNG.
aktar qr 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 --png cover-qr.png
Saved to cover-qr.png

aktar login

Kiểm tra token với Aktar rồi lưu lại, để các lệnh khác có thể kết nối.

Cách dùng

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

Tùy chọn

CờGiá trịMô tả
--token<token>Token, thay cho lời nhắc.
--port<port>Cổng của Aktar, được lưu cùng token. Mặc định 47913.

Cần biết

  • Trong terminal, lệnh hỏi token và ẩn những gì bạn gõ. Khi đầu vào được truyền qua pipe, lệnh đọc token từ đó.
  • --token bỏ qua lời nhắc, nhưng các chương trình khác có thể thấy token trong lúc lệnh chạy, và token sẽ nằm trong lịch sử shell của bạn, nên aktar sẽ cảnh báo. Truyền qua pipe hoặc dùng AKTAR_TOKEN sẽ tránh được điều đó.
  • Token bị Aktar từ chối sẽ không được lưu, và mã thoát là 3.

Ví dụ

Token được ẩn khi bạn gõ.
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
Trên Mac, với token đã sao chép từ Aktar.
pbpaste | aktar login
Connected to Aktar 0.10.0. Saved to /Users/you/.config/aktar/cli.json
Không có lời nhắc, với cổng đã đổi. aktar cảnh báo rằng token đã bị lộ ra.
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

Xóa token và cổng đã lưu.

Cách dùng

aktar logout

Tùy chọn

Không có tùy chọn.

Cần biết

  • AKTAR_TOKEN, nếu được đặt, vẫn hoạt động sau aktar logout.
  • Lệnh không ngắt kết nối các client khác. Để làm vậy, hãy tạo lại token trong Aktar.

Ví dụ

Quên token.
aktar logout
Logged out.
Sau đó, các lệnh yêu cầu bạn đăng nhập lại (mã thoát 3).
aktar status
aktar: Not connected to Aktar yet. Run aktar login with the token from Aktar's Settings > Integrations.

aktar status

Cho biết bạn đang kết nối với Aktar nào, trên cổng nào, đích đang chọn trong Aktar, và tệp cấu hình nằm ở đâu.

Cách dùng

aktar status [--json]

Tùy chọn

CờGiá trịMô tả
--jsonIn JSON thay vì văn bản.
--port<port>Cổng API cục bộ của Aktar, chỉ cho lệnh này. Được ưu tiên hơn AKTAR_PORT và cổng đã lưu.

Cần biết

  • Cách nhanh để kiểm tra kết nối trong script: lệnh thoát với mã 3 khi không liên lạc được với Aktar hoặc token sai.

Ví dụ

Đã kết nối, kèm đích đang chọn.
aktar status
Aktar 0.10.0 (build 28) on port 47913
Destination: Screenshots (Cloudflare R2, screenshots)
Config: /Users/you/.config/aktar/cli.json
Như trên, dạng JSON, dành cho script.
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

Liệt kê các đích cùng nhà cung cấp, bucket và ID. * đánh dấu đích đang chọn trong Aktar.

Cách dùng

aktar destinations [--json]

Tùy chọn

CờGiá trịMô tả
--jsonIn JSON thay vì văn bản.
--port<port>Cổng API cục bộ của Aktar, chỉ cho lệnh này. Được ưu tiên hơn AKTAR_PORT và cổng đã lưu.

Cần biết

  • Dùng tên hoặc ID với -d. Tên được so khớp không phân biệt chữ hoa chữ thường; ID luôn dùng được, kể cả sau khi đổi tên.
  • --json trả về id, name, provider, providerName, bucket, publicBaseURL và isDefault cho từng đích.

Ví dụ

Đích đang chọn được đánh dấu bằng *.
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
Tên của đích đang chọn, dùng jq.
aktar destinations --json | jq -r '.[] | select(.isDefault) | .name'
Screenshots

aktar history

Liệt kê các tệp tải lên gần đây, mới nhất trước: ngày, tên tệp và liên kết. Các từ sau history dùng để tìm trong lịch sử.

Cách dùng

aktar history [search] [options]

Tùy chọn

CờGiá trịMô tả
-n, --limit<n>Số tệp tải lên cần liệt kê. Mặc định 20.
-d, --destination<name|id>Chỉ các tệp tải lên đích này, theo tên hoặc ID.
--jsonIn JSON thay vì văn bản.
--port<port>Cổng API cục bộ của Aktar, chỉ cho lệnh này. Được ưu tiên hơn AKTAR_PORT và cổng đã lưu.

Cần biết

  • Lệnh liệt kê 20 tệp tải lên, trừ khi bạn truyền -n.
  • --json trả về cùng các trường như aktar upload --json, gồm cả id của từng tệp để dùng với aktar qr.

Ví dụ

Ba tệp tải lên gần nhất.
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
Tìm hóa đơn trong một đích.
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
Liên kết của bản build mới nhất, dùng jq.
aktar history -d Builds -n 1 --json | jq -r '.[0].url'
https://acme-builds.s3.amazonaws.com/2026/10/app-3f9c2e1.zip

aktar mcp

Chạy một máy chủ Model Context Protocol (MCP), để các tác nhân AI như Claude, Cursor, VS Code và Codex có thể tải tệp lên qua Aktar, tìm các tệp đã tải lên trước đó và tạo liên kết. Chỉ cần thêm vào tác nhân của bạn một lần; tác nhân sẽ tự khởi chạy khi cần.

Cách dùng

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

Tùy chọn

CờGiá trịMô tả
--root<folder>Chỉ tải lên các tệp từ thư mục này. Lặp lại để thêm thư mục khác. Mặc định: thư mục mà máy chủ đang chạy trong đó, hoặc không thư mục nào nếu đó là thư mục chính của bạn hoặc gốc ổ đĩa.
--read-onlyChỉ cung cấp các công cụ không thay đổi gì trong bucket: tìm kiếm, danh sách, liên kết tạm thời và hình thu nhỏ.
--allow-replaceCung cấp thêm replace_file, công cụ ghi đè một tệp trong bucket.
--allow-deleteCung cấp thêm delete_upload, công cụ xóa tệp khỏi bucket của nó, và replace_file.
--max-link-minutes<n>Thời gian tối đa một liên kết tạm thời còn hoạt động, tính bằng phút. Mặc định 60, tối đa 10080 (7 ngày).
--log<file>Ghi thêm mỗi lần gọi công cụ (thời gian, công cụ, đối số, kết quả) vào tệp này, chỉ bạn đọc được.
--port<port>Cổng API cục bộ của Aktar, chỉ cho lệnh này. Được ưu tiên hơn AKTAR_PORT và cổng đã lưu.

Cần biết

  • Hãy chạy aktar login trước. Máy chủ đọc token đã lưu ở mỗi lần gọi, nên đăng nhập lại vẫn hoạt động mà không cần khởi động lại tác nhân.
  • Tải lên nghĩa là công khai tệp: ai có liên kết đều mở được. Tác nhân sẽ hỏi trước khi gọi một công cụ trừ khi bạn cho phép.
  • Tệp chỉ được tải lên từ các thư mục bạn chỉ định bằng --root, hoặc nếu không có thì từ thư mục mà máy chủ đang chạy trong đó. Nếu đó là thư mục chính (home) của bạn hoặc gốc ổ đĩa, như một số ứng dụng vẫn làm, sẽ không có tệp cục bộ nào được tải lên cho đến khi bạn thêm --root. --root ~ cho phép toàn bộ thư mục chính của bạn, nếu bạn thật sự muốn vậy. Đường dẫn được phân giải, kể cả symlink, trước khi kiểm tra.
  • Bí mật không bao giờ được tải lên, dù nằm ở đâu: khóa SSH và khóa riêng tư, tệp .env, thông tin xác thực của dịch vụ đám mây và trình quản lý gói (~/.aws, ~/.kube, ~/.npmrc và các tệp khác), cấu hình của chính Aktar, Keychain, hồ sơ trình duyệt và cơ sở dữ liệu mật khẩu. Tệp có nhiều hard link cũng bị từ chối. Để chia sẻ một trong số này, hãy tự tải lên bằng aktar upload.
  • --read-only chỉ cung cấp các công cụ không thay đổi gì trong bucket. replace_file ghi đè tệp giống như xóa, nên chỉ được cung cấp khi có --allow-replace, còn delete_upload chỉ khi có --allow-delete (cờ này cũng cung cấp replace_file).
  • create_temporary_link tạo liên kết dài tối đa 60 phút, trừ khi --max-link-minutes cho phép lâu hơn. upload_clipboard bị bỏ ra khi bạn dùng --root, vì clipboard có thể chứa bất cứ thứ gì.
  • Kết quả của công cụ bắt đầu bằng một ghi chú rằng tên tệp, khóa và thông điệp trong đó là dữ liệu, không phải chỉ dẫn, và --log ghi lại mọi lần gọi. Máy chủ chạy tối đa 4 lần gọi công cụ cùng lúc.
  • Nếu không cài đặt toàn cục, hãy dùng npx -y @getaktar/cli mcp --root ~/Projects làm lệnh.
  • Hỗ trợ phiên bản MCP hiện tại (2026-07-28) và các phiên bản trước bắt đầu bằng initialize (từ 2024-11-05 đến 2025-11-25), qua stdio. Cần aktar 0.4.0; các giới hạn ở trên có từ aktar 0.6.0.

Công cụ

Công cụChức năng
upload_fileTải một tệp lên và trả về liên kết, Markdown và HTML của nó. Đích, tên, thư mục và thời hạn là tùy chọn. short yêu cầu tạo liên kết ngắn, hoặc không tạo.
upload_clipboardTải lên tệp hoặc hình ảnh đang có trong clipboard. short yêu cầu tạo liên kết ngắn, hoặc không tạo. Không có khi dùng --root.
replace_fileGhi một tệp mới đè lên tệp đã tải lên hoặc bất kỳ tệp nào trong bucket, giữ nguyên liên kết. Chỉ có khi dùng --allow-replace hoặc --allow-delete. Cần Aktar cho Mac 0.14.0 hoặc Windows 0.7.0.
create_short_linkTạo liên kết ngắn cho một tệp tải lên bằng dịch vụ rút gọn của đích, hoặc trả về liên kết đã có. Không có khi dùng --read-only. Cần Aktar cho Mac 0.17.0 hoặc Windows 0.10.0.
search_uploadsTìm trong lịch sử tải lên.
list_destinationsLiệt kê các đích và loại tệp mà mỗi đích được dùng cho.
list_bucketLiệt kê thư mục và tệp của một bucket, kể cả các tệp không được tải lên bằng Aktar.
create_temporary_linkTạo liên kết ngừng hoạt động sau một thời gian (presigned URL). Cho đến lúc đó, ai có liên kết đều tải được tệp, kể cả từ bucket riêng tư. Tối đa 60 phút trừ khi --max-link-minutes cho phép lâu hơn.
get_thumbnailCho tác nhân xem bản xem trước của một tệp đã tải lên. Cần Aktar cho Mac 0.13.0 hoặc Windows 0.6.0.
list_watched_foldersLiệt kê các thư mục được theo dõi và trạng thái của chúng.
get_statusKiểm tra kết nối với Aktar.
delete_uploadXóa một tệp đã tải lên khỏi bucket của nó. Chỉ khi có --allow-delete.

Ví dụ

Thêm Aktar vào Claude Code hoặc Codex.
claude mcp add aktar -- aktar mcp --root ~/Projects
codex mcp add aktar -- aktar mcp --root ~/Projects
Cho phép tác nhân tải lên từ hai thư mục và thay thế tệp.
claude mcp add aktar -- aktar mcp --root ~/Projects --root ~/Desktop --allow-replace
Lưu lại những gì tác nhân đã làm.
claude mcp add aktar -- aktar mcp --root ~/Projects --log ~/aktar-mcp.log

aktar skill

In ra một skill cho tác nhân (SKILL.md) hướng dẫn tác nhân dùng lệnh aktar với --json: chạy gì, đọc kết quả ra sao, và chỉ tải lên những gì bạn yêu cầu chia sẻ. Dành cho các tác nhân dùng skill nhưng không dùng MCP.

Cách dùng

aktar skill

Tùy chọn

Không có tùy chọn.

Cần biết

  • Hãy lưu nó ở nơi tác nhân của bạn tìm skill, ví dụ ~/.claude/skills/aktar/ cho Claude Code.

Ví dụ

Cài skill cho Claude Code.
mkdir -p ~/.claude/skills/aktar
aktar skill > ~/.claude/skills/aktar/SKILL.md

Tùy chọn cho mọi lệnh

CờGiá trịMô tả
-h, --helpHiển thị danh sách lệnh và tùy chọn.
-v, --versionHiển thị phiên bản của aktar.
--port<port>Cổng API cục bộ của Aktar, chỉ cho lệnh này. Được ưu tiên hơn AKTAR_PORT và cổng đã lưu.

Đầu ra

Định dạng

-f chọn nội dung in ra cho từng tệp. Không có nó, aktar in URL thuần, bất kể thanh menu của Aktar sao chép theo định dạng nào. Markdown và HTML nhúng hình ảnh và tạo liên kết cho mọi tệp khác, giống cách Aktar làm.

Định dạngIn ra cho photo.jpg
-f urlhttps://files.example.com/2026/10/7f3c2a91.jpgLiên kết (mặc định).
-f markdown![](https://files.example.com/2026/10/7f3c2a91.jpg)Hình ảnh Markdown, hoặc liên kết Markdown cho tệp khác.
-f html<img src="https://files.example.com/2026/10/7f3c2a91.jpg" alt="">Thẻ <img>, hoặc liên kết <a> cho tệp khác.
-f custom![photo.jpg](https://files.example.com/2026/10/7f3c2a91.jpg)Mẫu của bạn trong cài đặt của Aktar, với {url}, {filename} và các biến khác đã được điền.

stdout và stderr

Đầu ra chuẩn chỉ nhận liên kết, mỗi dòng một liên kết, theo thứ tự các tệp (và mã QR, khi có --qr). Mọi thứ khác đi vào đầu ra lỗi chuẩn: tiến trình, lỗi và ghi chú như aktar: photo.jpg: already uploaded, reused the existing link. Nhờ vậy url=$(aktar upload file) và aktar upload *.png > links.txt luôn nhận được liên kết sạch.

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

JSON

--json in một mảng, mỗi tệp đã tải lên một phần tử, sau khi tất cả đã xong. Lượt tải lên thất bại bị bỏ ra (chúng được báo trên stderr), nên hãy kiểm tra cả mã thoát.

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",
    "shortUrl": null,
    "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
  }
]
TrườngÝ nghĩa
idID của tệp trong lịch sử của Aktar. aktar qr nhận giá trị này.
filenameTên tệp mà Aktar ghi nhận: tên gốc của tệp, hoặc --name.
objectKeyVị trí của tệp trong bucket.
urlLiên kết.
shortUrlLiên kết ngắn, hoặc null nếu không có. formats đã dùng nó.
destinationIdID của đích.
destinationNameTên của đích.
mimeTypeLoại tệp, sau khi Aktar chuyển đổi (nếu có).
sizeDung lượng tính bằng byte, như khi lưu.
createdAtThời điểm tải lên (ISO 8601, UTC).
expiresAtThời điểm bucket xóa tệp, hoặc null nếu tệp được giữ.
replacedAtThời điểm tệp được thay thế lần gần nhất (ISO 8601, UTC). Bị bỏ ra cho đến khi tệp được thay thế, và ở các phiên bản Aktar trước Mac 0.14.0 và Windows 0.7.0.
formatsLiên kết ở cả bốn định dạng: url, markdown, html và custom.
reusedtrue khi không có gì được tải lên vì tệp giống hệt đã có sẵn. Bị bỏ ra ở các phiên bản Aktar trước Mac 0.10.0 và Windows 0.3.0.
shortLinkErrorLý do Aktar không tạo được liên kết ngắn; khi đó url là liên kết gốc. Không có nếu mọi thứ suôn sẻ.

Mã thoát

MãÝ nghĩa
0Mọi thứ đều thành công.
1Ít nhất một lượt tải lên hoặc yêu cầu thất bại; các tệp khác vẫn được tải lên. Lỗi của chính Aktar, chẳng hạn chưa thiết lập tự động xóa, cũng kết thúc ở đây.
2Đối số sai, tệp không tồn tại, hoặc tên đích mà Aktar không có. Không có gì được tải lên.
3Chưa đăng nhập, Aktar không chạy, API cục bộ đang tắt, token sai, hoặc ứng dụng trên cổng đó không chứng minh được nó là Aktar (hoặc quá cũ để làm việc này).

Công thức

Sao chép, sửa tên tệp, xong. Mọi công thức chỉ dùng những gì đã được mô tả ở trên.

Lưu liên kết vào biến

Chỉ liên kết đi vào đầu ra chuẩn, nên phép thay thế lệnh nhận đúng URL. || exit 1 dừng script nếu tải lên thất bại.

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

Tải lên bản build và đăng liên kết

Nén bản build thành zip, tải lên đích tên Builds với hash rút gọn của commit, rồi đăng liên kết lên bất kỳ webhook nào nhận JSON (kênh chat, hệ thống quản lý issue, endpoint của riêng bạn). set -e dừng lại trước khi đăng nếu tải lên thất bại.

#!/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\"}"

Một target trong Makefile

make share tải lên báo cáo với ngày hôm nay và lưu liên kết vào .last-link. Trong Makefile, $$ truyền một ký tự $ cho shell, và dòng lệnh bắt đầu bằng một tab.

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

Trình tải ảnh lên cho Typora

Trong Typora, mở Settings > Image, chọn Custom Command làm trình tải ảnh lên và nhập đường dẫn đầy đủ đến aktar (đường dẫn mà which aktar in ra) theo sau là upload. Typora truyền đường dẫn của ảnh và đọc mỗi dòng một liên kết.

/opt/homebrew/bin/aktar upload

Từng bước, kèm cài đặt When Insert…: Tải ảnh Typora lên S3.

Tải lên từ Finder hoặc Phím tắt

Trên Mac, thêm tác vụ Chạy tập lệnh shell vào một phím tắt, hoặc vào một Tác vụ nhanh của Automator nhận tệp trong Finder, và đặt chế độ truyền đầu vào dưới dạng đối số. Phím tắt và Automator không tải PATH của shell, vì vậy mới có dòng đầu tiên. Chọn tệp, chạy, và các liên kết đã nằm trong bộ nhớ tạm.

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

Nó tải lên tệp, không phải thư mục. Nhiều tệp cho ra nhiều liên kết, mỗi dòng một liên kết.

Tệp tạm thời

Với tệp log, bản ghi màn hình hay bất cứ thứ gì không nên để lâu, hãy để bucket tự xóa. Trước tiên đích cần có quy tắc tự động xóa của Aktar: thiết lập một lần từ Xóa sau trên thanh menu của Aktar hoặc trong cài đặt của đích.

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

Tệp có hạn được đặt trong tmp/1d/, tmp/7d/, v.v. trong bucket, và bucket xóa chúng ngay cả khi Aktar không chạy.

Mở liên kết trên điện thoại

--qr in mã QR bên dưới liên kết; hãy hướng camera điện thoại vào terminal. Để hiển thị lại sau này, truyền ID tải lên cho aktar qr, ở đây là tệp tải lên mới nhất khớp với “demo”.

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

Windows PowerShell

Cách này cũng dùng được trong PowerShell. $LASTEXITCODE chứa mã thoát, và ConvertFrom-Json đọc --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 trong Claude Desktop, Cursor hoặc VS Code

Các ứng dụng nhận cấu hình JSON cho máy chủ MCP (Claude Desktop, Cursor, Windsurf và những ứng dụng khác) cần mục này. VS Code dùng cùng mục đó trong servers của .vscode/mcp.json. Sau đó hãy nhờ tác nhân của bạn tải một tệp lên, tìm ảnh chụp màn hình tuần trước hoặc tạo liên kết tạm thời.

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

Nếu ứng dụng không tìm thấy aktar, hãy dùng đường dẫn đầy đủ của nó (which aktar), hoặc npx với ["-y", "@getaktar/cli", "mcp", "--root", "/Users/you/Projects"] làm đối số. Đặt thư mục mà tác nhân được phép tải lên từ đó sau --root (trên Windows, ví dụ C:\\Users\\you\\Projects).

Aktar làm gì cho bạn

CLI chỉ chuyển tệp đi; phần còn lại do Aktar làm, theo cài đặt của từng đích. Vì vậy mọi thứ bạn thiết lập trong ứng dụng cũng áp dụng cho aktar upload, không cần thêm tùy chọn nào, và liên kết bạn nhận được là liên kết của tệp như khi được lưu.

  • Mẫu đường dẫn

    Đường dẫn đối tượng của đích đặt tên tệp, với {year}, {uuid}, {filename} và các biến khác. {md5} và {sha256} đặt tên tệp theo nội dung.

  • Xử lý hình ảnh

    Nếu đích chuyển ảnh sang WebP hoặc AVIF, nén hoặc đổi kích thước ảnh, các tệp tải lên từ CLI cũng được xử lý như vậy, và liên kết trỏ đến tệp đã chuyển đổi.

  • Siêu dữ liệu ảnh

    Siêu dữ liệu hình ảnh trong phần mặc định tải lên của đích xóa vị trí khỏi ảnh, hoặc toàn bộ siêu dữ liệu, trước khi ảnh rời khỏi máy tính của bạn.

  • Cùng tệp, cùng liên kết

    Khi bật Dùng lại liên kết cho tệp trùng lặp, nội dung giống hệt trong cùng đích sẽ nhận liên kết có sẵn thay vì tải lên lần thứ hai. aktar ghi chú điều đó trên stderr.

  • Tệp lớn

    Tệp lớn được tải lên theo từng phần, không có giới hạn 5 GB, được thử lại khi mất kết nối và tiếp tục từ chỗ đã dừng. aktar truyền tệp dạng luồng đến Aktar, nên không bao giờ nạp cả tệp vào bộ nhớ.

  • Liên kết công khai hoặc tạm thời

    Liên kết là công khai hay tạm thời (presigned), loại dùng được cả cho bucket riêng tư, là do đích quyết định, giống như trong ứng dụng.

Liên kết cho tệp trùng lặp, xử lý hình ảnh, {md5} và {sha256} cùng tải lên theo phần có từ Aktar cho Mac 0.10.0 và Windows 0.3.0: có gì mới trong 0.10.0.

Khắc phục sự cố

Thông báo lỗi của aktar bắt đầu bằng aktar: và đi vào stderr. Mã thoát cho biết đó là loại sự cố gì.

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

Mở Aktar và kiểm tra rằng Cho phép kết nối cục bộ đang bật trong Cài đặt > Tích hợp. Nếu bạn đã đổi cổng ở đó, hãy truyền cổng bằng --port hoặc AKTAR_PORT, hoặc chạy lại aktar login --port. Mã thoát 3.

Not connected to Aktar yet

Không có token đã lưu và không có AKTAR_TOKEN. Chạy aktar login với token từ Cài đặt > Tích hợp của Aktar. Mã thoát 3.

The token doesn't match Aktar's anymore

Token đã được tạo lại trong Aktar, hoặc bị gõ sai. Chạy lại aktar login với token hiện tại. Nếu AKTAR_TOKEN được đặt, nó được ưu tiên hơn token đã lưu, nên hãy cập nhật hoặc bỏ đặt biến đó. Mã thoát 3.

The app on port … couldn't prove it's Aktar

Có thứ gì đó trả lời trên cổng của Aktar nhưng không chứng minh được nó có token của bạn, nên token không được gửi đi. Nếu Aktar đang chạy, nhiều khả năng token của nó đã thay đổi: hãy chạy lại aktar login. Nếu Aktar không chạy, hãy mở nó. Mã thoát 3.

This version of Aktar can't prove it's Aktar

aktar 0.6.0 trở lên kiểm tra ứng dụng trước khi gửi token, việc này cần Aktar cho Mac 0.18.0 hoặc Aktar cho Windows 0.11.0 trở lên. Hãy cập nhật Aktar (ứng dụng tự đề xuất bản cập nhật), và lệnh sẽ hoạt động trở lại. Mã thoát 3.

MCP: This server doesn't upload local files

Tác nhân đã khởi chạy aktar mcp trong thư mục chính của bạn hoặc ở gốc ổ đĩa, và không có --root. Hãy thêm --root cùng thư mục được phép lấy tệp vào lệnh hoặc cấu hình của máy chủ, ví dụ aktar mcp --root ~/Projects, rồi khởi động lại tác nhân.

Auto-delete isn't set up for this destination

--expires cần quy tắc tự động xóa của bucket. Thiết lập một lần từ Xóa sau trên thanh menu của Aktar hoặc trong cài đặt của đích, hoặc tải lên mà không dùng --expires. Mã thoát 1.

No destination named "…"

Thông báo liệt kê các tên mà Aktar có. Kiểm tra chính tả, đặt tên có dấu cách trong dấu ngoặc kép (-d "Client work"), hoặc dùng ID từ aktar destinations. Mã thoát 2.

Tải lên tệp lớn mất nhiều thời gian

Đó là tốc độ của nhà cung cấp lưu trữ: aktar không giới hạn thời gian tải lên và hiển thị tiến trình trên stderr trong terminal. Hãy để Aktar chạy cho đến khi xong. Nếu mất kết nối hoặc Aktar thoát (Aktar closed the connection before the request finished), hãy tải lại cùng tệp đó: Aktar cho Mac 0.10.0 và Windows 0.3.0 tiếp tục từ phần cuối cùng.

aktar không khởi động: SyntaxError hoặc parseArgs

Node.js của bạn cũ hơn bản 18. Kiểm tra bằng node --version và cập nhật, hoặc cài aktar bằng Homebrew, vốn đi kèm Node.js riêng.

PowerShell báo việc chạy script bị vô hiệu hóa

Chính sách thực thi của PowerShell chặn script mà npm cài cho aktar. Hãy chạy aktar.cmd thay thế, hoặc cho phép script cục bộ một lần bằng Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.