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,--qrvàaktar qrcầ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 replacecầ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-shortvàaktar shortcầ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/cliVới Homebrew (macOS)
brew install getaktar/tap/aktar-cliHoặc chạy một lần mà không cần cài gì:
npx @getaktar/cli upload file.pngKiểm tra phiên bản bạn đang có:
aktar --version
0.6.0Kết nối với Aktar
- 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ó ở đó. - Sao chép token hiển thị bên dưới.
- Chạy
aktar loginvà dán token vào lời nhắcToken:. 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.jsonToken đượ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.
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ến | Tác dụng |
|---|---|
AKTAR_TOKEN | Token từ Cài đặt > Tích hợp của Aktar. Được dùng thay cho token đã lưu. |
AKTAR_PORT | Cổng API cục bộ của Aktar, nếu bạn đã đổi. --port được ưu tiên hơn. |
NO_COLOR | Vẽ mã QR bằng ký tự thường thay vì màu của terminal. |
XDG_CONFIG_HOME | Vị 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 uploadaktar upload --clipboardaktar replaceaktar shortaktar qraktar loginaktar logoutaktar statusaktar destinationsaktar historyaktar mcpaktar skill
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. |
--short | Tạ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-short | Lần này không tạo liên kết ngắn. | |
--qr | In thêm mã QR cho từng liên kết. | |
--json | In 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à
aktarthoá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 đó. --namechỉ 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 covertảiIMG_4021.jpglên thànhcover.jpg. Với--folder, đó là tên bên trong thư mục.--expiresnhậ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.--qrkhông thể kết hợp với--json, và--pngchỉ dùng được vớiaktar 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à
--formatcùng--qrđều dùng nó.--shorttạ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-shortthì 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ụ
aktar upload screenshot.png
https://files.example.com/2026/10/7f3c2a91.pngaktar upload *.png -f markdown

aktar upload IMG_4021.jpg --name cover --folder blog/2026
https://files.example.com/blog/2026/cover.jpgaktar upload photo.jpg
aktar: photo.jpg: already uploaded, reused the existing link
https://files.example.com/2026/09/4d2a8c61.jpgaktar upload talk.pdf --short
https://s.example.com/k3Tq9aktar 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ả |
|---|---|---|
--clipboard | Tả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. |
--short | Tạ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-short | Lần này không tạo liên kết ngắn. | |
--qr | In thêm mã QR cho từng liên kết. | |
--json | In 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. --namevà--folderchỉ dùng với tệp.-d,-f,--expires,--qrvà--jsonhoạ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ụ
aktar upload --clipboard
https://files.example.com/2026/10/9a4c03be.pngaktar upload --clipboard -f markdown -d Blog
aktar upload --clipboard --expires 1
https://files.example.com/tmp/1d/2026/10/38f0d7c2.pngaktar 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). |
--qr | In thêm mã QR cho từng liên kết. | |
--json | In 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,--namevà--clipboardkhô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ụ
aktar replace 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 report-v2.pdf
https://files.example.com/2026/09/0e7d51b3.pdfaktar 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ả |
|---|---|---|
--json | In 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. | |
--qr | In 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.aktartì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.
--jsonin 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.--qrthê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ụ
aktar short 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1
https://s.example.com/Qm3xZaktar 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à
idtừaktar history --jsonhoặcaktar upload --json.aktartì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. --pnglư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ụ
aktar qr https://files.example.com/2026/10/demo.mp4aktar qr 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 --png cover-qr.png
Saved to cover-qr.pngaktar 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ừ đó.
--tokenbỏ 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ênaktarsẽ cảnh báo. Truyền qua pipe hoặc dùngAKTAR_TOKENsẽ 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ụ
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.jsonpbpaste | aktar login
Connected to Aktar 0.10.0. Saved to /Users/you/.config/aktar/cli.jsonaktar 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.jsonaktar logout
Xóa token và cổng đã lưu.
Cách dùng
aktar logoutTù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 sauaktar 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ụ
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
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ả |
|---|---|---|
--json | In 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ụ
aktar status
Aktar 0.10.0 (build 28) on port 47913
Destination: Screenshots (Cloudflare R2, screenshots)
Config: /Users/you/.config/aktar/cli.jsonaktar 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ả |
|---|---|---|
--json | In 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. --jsontrả vềid,name,provider,providerName,bucket,publicBaseURLvàisDefaultcho từng đích.
Ví dụ
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-9D5F2A7E4B13aktar destinations --json | jq -r '.[] | select(.isDefault) | .name'
Screenshotsaktar 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. |
--json | In 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. --jsontrả về cùng các trường nhưaktar upload --json, gồm cảidcủa từng tệp để dùng vớiaktar qr.
Ví dụ
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.pdfaktar 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.pdfaktar history -d Builds -n 1 --json | jq -r '.[0].url'
https://acme-builds.s3.amazonaws.com/2026/10/app-3f9c2e1.zipaktar 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-only | Chỉ 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-replace | Cung cấp thêm replace_file, công cụ ghi đè một tệp trong bucket. | |
--allow-delete | Cung 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 logintrướ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,~/.npmrcvà 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ằngaktar upload. --read-onlychỉ cung cấp các công cụ không thay đổi gì trong bucket.replace_fileghi đè tệp giống như xóa, nên chỉ được cung cấp khi có--allow-replace, còndelete_uploadchỉ khi có--allow-delete(cờ này cũng cung cấpreplace_file).create_temporary_linktạo liên kết dài tối đa 60 phút, trừ khi--max-link-minutescho phép lâu hơn.upload_clipboardbị 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à
--logghi 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 ~/Projectslà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_file | Tả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_clipboard | Tả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_file | Ghi 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_link | Tạ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_uploads | Tìm trong lịch sử tải lên. |
list_destinations | Liệt kê các đích và loại tệp mà mỗi đích được dùng cho. |
list_bucket | Liệ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_link | Tạ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_thumbnail | Cho 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_folders | Liệt kê các thư mục được theo dõi và trạng thái của chúng. |
get_status | Kiểm tra kết nối với Aktar. |
delete_upload | Xóa một tệp đã tải lên khỏi bucket của nó. Chỉ khi có --allow-delete. |
Ví dụ
claude mcp add aktar -- aktar mcp --root ~/Projects
codex mcp add aktar -- aktar mcp --root ~/Projectsclaude mcp add aktar -- aktar mcp --root ~/Projects --root ~/Desktop --allow-replaceclaude mcp add aktar -- aktar mcp --root ~/Projects --log ~/aktar-mcp.logaktar 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 skillTù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ụ
mkdir -p ~/.claude/skills/aktar
aktar skill > ~/.claude/skills/aktar/SKILL.mdTùy chọn cho mọi lệnh
| Cờ | Giá trị | Mô tả |
|---|---|---|
-h, --help | Hiển thị danh sách lệnh và tùy chọn. | |
-v, --version | Hiể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ạng | In ra cho photo.jpg |
|---|---|
-f url | https://files.example.com/2026/10/7f3c2a91.jpgLiên kết (mặc định). |
-f markdown | 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 | 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.jpgJSON
--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": "",
"html": "<img src=\"https://files.example.com/2026/10/7f3c2a91.jpg\" alt=\"\">",
"custom": ""
},
"reused": false
}
]| Trường | Ý nghĩa |
|---|---|
id | ID của tệp trong lịch sử của Aktar. aktar qr nhận giá trị này. |
filename | Tên tệp mà Aktar ghi nhận: tên gốc của tệp, hoặc --name. |
objectKey | Vị trí của tệp trong bucket. |
url | Liên kết. |
shortUrl | Liên kết ngắn, hoặc null nếu không có. formats đã dùng nó. |
destinationId | ID của đích. |
destinationName | Tên của đích. |
mimeType | Loại tệp, sau khi Aktar chuyển đổi (nếu có). |
size | Dung lượng tính bằng byte, như khi lưu. |
createdAt | Thời điểm tải lên (ISO 8601, UTC). |
expiresAt | Thời điểm bucket xóa tệp, hoặc null nếu tệp được giữ. |
replacedAt | Thờ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. |
formats | Liên kết ở cả bốn định dạng: url, markdown, html và custom. |
reused | true 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. |
shortLinkError | Lý 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 |
|---|---|
0 | Mọ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. |
3 | Chư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.pdfTả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.
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 uploadTừ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 --qrTệ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.
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.
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.
aktarghi 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.
aktartruyề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.
