• Aktar CLI

Dokumentacja aktar CLI

Każde polecenie, opcja i wynik aktar, z przykładami do wklejenia. Jesteś tu pierwszy raz? Przegląd CLI przeczytasz szybciej.

Przegląd CLI

Przegląd

aktar to pilot do aplikacji Aktar na tym samym komputerze. Przekazujesz mu pliki, on podaje je Aktarowi na 127.0.0.1, a Aktar przesyła je z użyciem miejsc docelowych, kluczy, szablonów ścieżek i ustawień linków, które już masz skonfigurowane. Link wraca do twojego terminala.

Czym jest

  • Małym poleceniem Node.js do skryptów, zadań CI na twoim własnym Macu lub komputerze z Windows i edytorów takich jak Typora
  • Sposobem na przesyłanie plików i zawartości schowka, wyświetlanie kodów QR oraz odczyt miejsc docelowych i historii przesyłania
  • Darmowym narzędziem open source (MIT), tak jak aplikacja

Czym nie jest

  • Nie działa samodzielnie: bez uruchomionego Aktara niczego nie prześle. Nigdy nie przechowuje twoich kluczy do magazynu
  • Nie jest do serwerów z Linuksem ani zdalnych maszyn: rozmawia tylko z Aktarem na tym samym komputerze. Tam użyj CLI swojego dostawcy magazynu

Wymagania

  • Aktar dla Maca 0.18.0 lub Aktar dla Windows 0.11.0 albo nowszy, z co najmniej jednym miejscem docelowym. aktar 0.5.0 i starsze działają z Aktarem dla Maca 0.4.0 lub nowszym
  • Node.js 18 lub nowszy (Homebrew zainstaluje go za ciebie)
  • --name, --qr i aktar qr wymagają aktar 0.2.0 lub nowszego
  • Ponowne użycie linku do pliku, który został już przesłany, wymaga aktar 0.2.0 oraz Aktara dla Maca 0.10.0 lub Aktara dla Windows 0.3.0
  • aktar replace wymaga aktar 0.3.0 oraz Aktara dla Maca 0.14.0 lub Aktara dla Windows 0.7.0 albo nowszego
  • --short, --no-short i aktar short wymagają aktar 0.5.0 oraz Aktar dla Maca 0.17.0 lub Aktar dla Windows 0.10.0, ze skracaczem linków ustawionym w miejscu docelowym

Instalacja

Zainstaluj je raz, przez npm albo Homebrew. Oba sposoby dodają polecenie aktar do twojej ścieżki.

Przez npm (macOS i Windows)

npm install -g @getaktar/cli

Przez Homebrew (macOS)

brew install getaktar/tap/aktar-cli

Albo uruchom je jednorazowo, bez instalowania czegokolwiek:

npx @getaktar/cli upload file.png

Sprawdź, którą wersję masz:

aktar --version
0.6.0

Połączenie z Aktarem

  1. W Aktarze dla Maca lub Windows otwórz Ustawienia > Integracje i włącz Zezwalaj na połączenia lokalne. Aktar nasłuchuje wtedy tylko na 127.0.0.1, na porcie 47913, chyba że zmienisz go w tym miejscu.
  2. Skopiuj token wyświetlony pod spodem.
  3. Uruchom aktar login i wklej token po monicie Token:. Podczas wpisywania pozostaje ukryty i jest sprawdzany w Aktarze przed zapisaniem, więc literówka nie zostanie zapisana.
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

Gdzie przechowywany jest token

aktar login zapisuje token i port w ~/.config/aktar/cli.json na Macu (albo w $XDG_CONFIG_HOME/aktar/cli.json, jeśli ją ustawisz) i w %APPDATA%\aktar\cli.json na Windows. Tylko twój użytkownik może go odczytać.

Przed wysłaniem tokenu aktar prosi aplikację na tym porcie, żeby udowodniła, że ma ten sam token, bez wysyłania go. Jeśli więc Aktar nie działa, a na jego porcie nasłuchuje inny program, ten program nie dostanie ani tokenu, ani twoich plików. Wymaga to Aktara dla Maca 0.18.0 lub Aktara dla Windows 0.11.0 albo nowszego; ze starszym Aktarem aktar zatrzymuje się i prosi o aktualizację.

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

aktar logout usuwa ten plik. Aby odciąć wszystkich klientów naraz, kliknij Wygeneruj ponownie obok tokenu w Aktarze, a potem uruchom aktar login jeszcze raz z nowym tokenem.

Skrypty i CI

Na maszynie do budowania pomiń aktar login i ustaw AKTAR_TOKEN (oraz AKTAR_PORT, jeśli zmieniłeś port). Mają one pierwszeństwo przed zapisanym plikiem. Aktar musi działać na tej maszynie, w tej samej sesji użytkownika.

AKTAR_TOKEN="$AKTAR_SECRET" aktar upload dist/app.zip -d Builds
ZmiennaDo czego służy
AKTAR_TOKENToken z Ustawienia > Integracje w Aktarze. Używany zamiast zapisanego.
AKTAR_PORTPort lokalnego API Aktara, jeśli go zmieniłeś. --port ma przed nim pierwszeństwo.
NO_COLORRysuje kody QR zwykłymi znakami zamiast kolorami terminala.
XDG_CONFIG_HOMELokalizacja folderu konfiguracji na macOS (domyślnie ~/.config). Na Windows używany jest %APPDATA%.

Polecenia

Wszystkie polecenia komunikują się z Aktarem, z wyjątkiem aktar qr ze zwykłym tekstem lub linkiem. Bez -d pliki trafiają do miejsca docelowego wybranego na pasku menu Aktara i pojawiają się w historii Aktara jak każde inne. aktar --help wypisuje tę samą listę. W Aktarze dla Maca 0.14.0 lub Aktarze dla Windows 0.7.0 albo nowszym przesyłanie bez -d najpierw stosuje reguły Używaj dla miejsc docelowych, więc obraz może trafić do miejsca docelowego na zrzuty ekranu, a build do innego.

aktar upload

Przesyła jeden lub więcej plików i wypisuje po jednym linku na plik, w kolejności, w miarę jak każdy się kończy.

Użycie

aktar upload <file>... [options]

Opcje

FlagaWartośćOpis
-d, --destination<name|id>Miejsce docelowe przesyłania, po nazwie lub ID. Domyślnie: to wybrane w Aktarze.
-f, --format<format>Co wypisać: url (domyślnie), markdown, html lub custom (twój szablon w Aktarze).
--name<name>Prześlij jeden plik pod tą nazwą. Jeśli nazwa nie ma rozszerzenia, zostaje rozszerzenie pliku.
--folder<path>Zachowaj nazwę pliku i prześlij go do tego folderu.
--expires<days>Niech bucket usunie plik po 1, 7, 14 lub 30 dniach. 0 go zachowuje.
--shortUtwórz krótki link skracaczem miejsca docelowego, nawet jeśli jego reguły pominęłyby ten plik.
--no-shortTym razem nie twórz krótkiego linku.
--qrWypisz też kod QR każdego linku.
--jsonWypisz tablicę JSON z pełnymi szczegółami każdego przesłanego pliku zamiast linków.
--port<port>Port lokalnego API Aktara, tylko dla tego polecenia. Ma pierwszeństwo przed AKTAR_PORT i zapisanym portem.

Warto wiedzieć

  • Każdy plik jest sprawdzany, zanim cokolwiek zostanie przesłane: jeśli któryś nie istnieje, nic nie jest przesyłane, a aktar kończy działanie z kodem 2.
  • Jeśli jedno przesyłanie się nie powiedzie, pozostałe i tak przejdą. Każdy błąd jest zgłaszany na stderr, a kod wyjścia to 1.
  • Bez --folder nazwę pliku nadaje szablon ścieżki miejsca docelowego, tak jak przy upuszczeniu na pasek menu. Z --folder plik zachowuje swoją nazwę w tym folderze.
  • --name działa z jednym plikiem naraz. Ukośniki są usuwane, a jeśli nazwa nie ma rozszerzenia, dodawane jest rozszerzenie pliku: --name cover przesyła IMG_4021.jpg jako cover.jpg. Z --folder to nazwa w folderze.
  • --expires przyjmuje 1, 7, 14 lub 30 (dni) albo 0, aby zachować plik. Bez tej opcji plik zostaje, niezależnie od ustawienia Usuń po w Aktarze. Wymaga reguł automatycznego usuwania Aktara w tym miejscu docelowym i nie można jej łączyć z --folder.
  • --qr nie można łączyć z --json, a --png działa tylko z aktar qr.
  • W terminalu postęp przesyłania pliku jest pokazywany na stderr. Plik jest przesyłany strumieniowo do Aktara, więc jego rozmiar nie ma znaczenia i nie ma limitu czasu.
  • Jeśli miejsce docelowe ma w Aktarze skracacz linków, wypisywany jest krótki link, a --format i --qr go używają. --short tworzy go, nawet gdy reguły miejsca docelowego pominęłyby ten plik, --no-short nie tworzy żadnego. Jeśli Aktar nie może go utworzyć, wypisywany jest oryginalny link, a stderr podaje powód.

Przykłady

Jeden plik, jeden link.
aktar upload screenshot.png
https://files.example.com/2026/10/7f3c2a91.png
Kilka plików jako Markdown: jedna linia na plik, w kolejności.
aktar upload *.png -f markdown
![](https://files.example.com/2026/10/1b9e44d0.png)
![](https://files.example.com/2026/10/c2f71a5e.png)
Przesłanie pod inną nazwą, do folderu.
aktar upload IMG_4021.jpg --name cover --folder blog/2026
https://files.example.com/blog/2026/cover.jpg
Ten sam plik był już w buckecie: link jest wypisywany jak zwykle, a informacja trafia na stderr.
aktar upload photo.jpg
aktar: photo.jpg: already uploaded, reused the existing link
https://files.example.com/2026/09/4d2a8c61.jpg
Ze skracaczem w miejscu docelowym wypisywany jest krótki link.
aktar upload talk.pdf --short
https://s.example.com/k3Tq9

aktar upload --clipboard

Przesyła plik lub obraz ze schowka, tak jak własny skrót schowka w Aktarze.

Użycie

aktar upload --clipboard [options]

Opcje

FlagaWartośćOpis
--clipboardPrześlij zawartość schowka zamiast plików.
-d, --destination<name|id>Miejsce docelowe przesyłania, po nazwie lub ID. Domyślnie: to wybrane w Aktarze.
-f, --format<format>Co wypisać: url (domyślnie), markdown, html lub custom (twój szablon w Aktarze).
--expires<days>Niech bucket usunie plik po 1, 7, 14 lub 30 dniach. 0 go zachowuje.
--shortUtwórz krótki link skracaczem miejsca docelowego, nawet jeśli jego reguły pominęłyby ten plik.
--no-shortTym razem nie twórz krótkiego linku.
--qrWypisz też kod QR każdego linku.
--jsonWypisz tablicę JSON z pełnymi szczegółami każdego przesłanego pliku zamiast linków.
--port<port>Port lokalnego API Aktara, tylko dla tego polecenia. Ma pierwszeństwo przed AKTAR_PORT i zapisanym portem.

Warto wiedzieć

  • Podaj pliki albo --clipboard, nie jedno i drugie.
  • --name i --folder działają tylko z plikami. -d, -f, --expires, --qr i --json działają tak jak z plikami.
  • Z --json nadal wypisuje tablicę, z jednym wpisem.

Przykłady

Zrzut ekranu, który właśnie skopiowałeś.
aktar upload --clipboard
https://files.example.com/2026/10/9a4c03be.png
Jako Markdown, do miejsca docelowego o nazwie Blog.
aktar upload --clipboard -f markdown -d Blog
![](https://blog-assets.example.com/2026/10/e5b2c8a4.png)
Usunięty przez bucket po jednym dniu.
aktar upload --clipboard --expires 1
https://files.example.com/tmp/1d/2026/10/38f0d7c2.png

aktar replace

Zapisuje nowy plik w miejsce przesłanego pliku, więc jego klucz i link pozostają takie same. Każdy, kto ma link, zobaczy nowy plik.

Użycie

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

Opcje

FlagaWartośćOpis
-d, --destination<name|id>Dla klucza: miejsce docelowe, w którego buckecie się znajduje, po nazwie lub ID. Domyślnie: to wybrane w Aktarze.
-f, --format<format>Co wypisać: url (domyślnie), markdown, html lub custom (twój szablon w Aktarze).
--qrWypisz też kod QR każdego linku.
--jsonWypisz tablicę JSON z pełnymi szczegółami każdego przesłanego pliku zamiast linków.
--port<port>Port lokalnego API Aktara, tylko dla tego polecenia. Ma pierwszeństwo przed AKTAR_PORT i zapisanym portem.

Warto wiedzieć

  • Pierwszy argument to ID przesłanego pliku albo link z aktar history (wpis w historii Aktara jest aktualizowany), a w przeciwnym razie klucz w buckecie z -d (gdy go pominiesz, w buckecie miejsca docelowego wybranego w Aktarze). Link, którego nie ma w historii Aktara, jest odrzucany: podaj wtedy jego klucz razem z -d.
  • Aktar usuwa metadane pliku i zmienia jego rozmiar zgodnie z ustawieniami miejsca docelowego, ale nigdy nie konwertuje go do innego formatu, więc rozszerzenie klucza się nie zmienia. Plik w tmp/{N}d/ zaczyna odliczać swoje N dni od nowa.
  • Klucz nigdy nie dostaje numeru i nic innego nie jest przesyłane. --folder, --expires, --name i --clipboard nie mają tu zastosowania i są odrzucane.
  • Stare kopie mogą przez jakiś czas pozostać w pamięci podręcznej CDN. Zajmie się tym Krótki czas buforowania miejsca docelowego albo czyszczenie pamięci podręcznej Cloudflare w Aktarze.
  • Wymaga Aktara dla Maca 0.14.0 lub Aktara dla Windows 0.7.0 albo nowszego.

Przykłady

Zastąpienie przesłanego pliku z historii po jego ID; link się nie zmienia.
aktar replace 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 report-v2.pdf
https://files.example.com/2026/09/0e7d51b3.pdf
Zastąpienie klucza w buckecie innego miejsca docelowego i wypisanie go jako Markdown.
aktar replace docs/guide.pdf guide.pdf -d Blog -f markdown
[guide.pdf](https://blog-assets.example.com/docs/guide.pdf)

aktar short

Tworzy krótki link dla przesłanego pliku z historii skracaczem jego miejsca docelowego i go wypisuje. Jeśli plik ma już krótki link, wypisuje ten.

Użycie

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

Opcje

FlagaWartośćOpis
--jsonWypisz szczegóły krótkiego linku jako JSON: dostawcę, stan i kliknięcia.
--qrWypisz też kod QR krótkiego linku.
--port<port>Port lokalnego API Aktara, tylko dla tego polecenia. Ma pierwszeństwo przed AKTAR_PORT i zapisanym portem.

Warto wiedzieć

  • Podaj ID przesłanego pliku albo link z aktar history; jego krótki link też zadziała. aktar szuka wśród ostatnich 1000 przesłanych plików.
  • Miejsce docelowe musi mieć skracacz w sekcji Krótkie linki w Aktarze: Shlink, YOURLS, Kutt, Dub, Short.io albo własne żądanie. Krótki link tworzy ten skracacz, więc twoje linki i dane o kliknięciach zostają w twojej infrastrukturze.
  • --json wypisuje szczegóły krótkiego linku: dostawcę, stan, a także kliknięcia i ostatnie kliknięcie, jeśli skracacz je liczy. --qr dodaje jego kod QR. Nie można ich łączyć.
  • Wymaga Aktar dla Maca 0.17.0 lub Aktar dla Windows 0.10.0. Starsze wersje odpowiadają, że jeszcze nie tworzą krótkich linków.

Przykłady

Krótki link dla przesłanego pliku z historii.
aktar short 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1
https://s.example.com/Qm3xZ

aktar qr

Pokazuje w terminalu kod QR linku lub dowolnego tekstu, żebyś mógł otworzyć go na telefonie. Po podaniu ID przesłanego pliku pokazuje jego link i kod QR.

Użycie

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

Opcje

FlagaWartośćOpis
--png<file>Zapisz kod QR jako plik PNG zamiast go wypisywać.
--port<port>Port lokalnego API Aktara, tylko dla tego polecenia. Ma pierwszeństwo przed AKTAR_PORT i zapisanym portem.

Warto wiedzieć

  • Podaj dokładnie jeden argument, a tekst ze spacjami ujmij w cudzysłów.
  • ID przesłanego pliku to id z aktar history --json lub aktar upload --json. aktar szuka go wśród ostatnich 1000 plików w historii Aktara; do zwykłego tekstu lub linku w ogóle nie potrzebuje Aktara.
  • W terminalu kod jest rysowany na czarno na białym, niezależnie od motywu. Gdy wyjście nie jest terminalem albo ustawiono NO_COLOR, jest rysowany bez kolorów.
  • --png zapisuje kod QR jako plik PNG zamiast go wypisywać.
  • Dla przesłanego pliku z krótkim linkiem pokazuje krótki link.

Przykłady

Kod QR dla dowolnego linku. Aparat telefonu go otworzy.
aktar qr https://files.example.com/2026/10/demo.mp4
Przesłany plik z historii, zapisany jako PNG.
aktar qr 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 --png cover-qr.png
Saved to cover-qr.png

aktar login

Sprawdza token w Aktarze i zapisuje go, żeby pozostałe polecenia mogły się połączyć.

Użycie

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

Opcje

FlagaWartośćOpis
--token<token>Token, zamiast monitu.
--port<port>Port Aktara, zapisywany razem z tokenem. Domyślnie 47913.

Warto wiedzieć

  • W terminalu prosi o token i ukrywa to, co wpisujesz. Gdy dane wejściowe są przekazywane potokiem, odczytuje token stamtąd.
  • --token pomija monit, ale podczas działania polecenia inne programy mogą zobaczyć token, a do tego trafia on do historii powłoki, więc aktar ostrzega przed tym. Przekazanie go potokiem albo AKTAR_TOKEN pozwala tego uniknąć.
  • Token odrzucony przez Aktar nie jest zapisywany, a kod wyjścia to 3.

Przykłady

Token pozostaje ukryty podczas wpisywania.
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
Na Macu, z tokenem skopiowanym z Aktara.
pbpaste | aktar login
Connected to Aktar 0.10.0. Saved to /Users/you/.config/aktar/cli.json
Bez monitu, dla zmienionego portu. aktar ostrzega, że token był widoczny.
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

Usuwa zapisany token i port.

Użycie

aktar logout

Opcje

Brak opcji.

Warto wiedzieć

  • AKTAR_TOKEN, jeśli jest ustawiony, nadal działa po aktar logout.
  • Nie rozłącza innych klientów. Aby to zrobić, wygeneruj token ponownie w Aktarze.

Przykłady

Zapomnij token.
aktar logout
Logged out.
Potem polecenia proszą o ponowne zalogowanie (kod wyjścia 3).
aktar status
aktar: Not connected to Aktar yet. Run aktar login with the token from Aktar's Settings > Integrations.

aktar status

Pokazuje, z którym Aktarem jesteś połączony, na którym porcie, które miejsce docelowe jest wybrane w Aktarze i gdzie jest plik konfiguracji.

Użycie

aktar status [--json]

Opcje

FlagaWartośćOpis
--jsonWypisz JSON zamiast tekstu.
--port<port>Port lokalnego API Aktara, tylko dla tego polecenia. Ma pierwszeństwo przed AKTAR_PORT i zapisanym portem.

Warto wiedzieć

  • Szybki sposób na sprawdzenie połączenia w skrypcie: kończy działanie z kodem 3, gdy Aktar jest nieosiągalny albo token jest nieprawidłowy.

Przykłady

Połączono, z wybranym miejscem docelowym.
aktar status
Aktar 0.10.0 (build 28) on port 47913
Destination: Screenshots (Cloudflare R2, screenshots)
Config: /Users/you/.config/aktar/cli.json
To samo jako JSON, do skryptów.
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

Wyświetla twoje miejsca docelowe z dostawcą, bucketem i ID. * oznacza to wybrane w Aktarze.

Użycie

aktar destinations [--json]

Opcje

FlagaWartośćOpis
--jsonWypisz JSON zamiast tekstu.
--port<port>Port lokalnego API Aktara, tylko dla tego polecenia. Ma pierwszeństwo przed AKTAR_PORT i zapisanym portem.

Warto wiedzieć

  • Użyj nazwy lub ID z -d. Wielkość liter w nazwach nie ma znaczenia; ID działa zawsze, nawet po zmianie nazwy.
  • --json zwraca dla każdego id, name, provider, providerName, bucket, publicBaseURL i isDefault.

Przykłady

Wybrane miejsce docelowe jest oznaczone *.
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
Nazwa wybranego miejsca docelowego, przez jq.
aktar destinations --json | jq -r '.[] | select(.isDefault) | .name'
Screenshots

aktar history

Wyświetla ostatnio przesłane pliki, od najnowszych: datę, nazwę pliku i link. Słowa po history przeszukują historię.

Użycie

aktar history [search] [options]

Opcje

FlagaWartośćOpis
-n, --limit<n>Ile przesłanych plików wyświetlić. Domyślnie 20.
-d, --destination<name|id>Tylko pliki przesłane do tego miejsca docelowego, po nazwie lub ID.
--jsonWypisz JSON zamiast tekstu.
--port<port>Port lokalnego API Aktara, tylko dla tego polecenia. Ma pierwszeństwo przed AKTAR_PORT i zapisanym portem.

Warto wiedzieć

  • Wyświetla 20 plików, chyba że podasz -n.
  • --json zwraca te same pola co aktar upload --json, w tym id każdego pliku do użycia z aktar qr.

Przykłady

Ostatnie trzy przesłane pliki.
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
Wyszukiwanie faktur w jednym miejscu docelowym.
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
Link do najnowszego buildu, przez 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

Uruchamia serwer Model Context Protocol (MCP), dzięki czemu agenci AI, tacy jak Claude, Cursor, VS Code i Codex, mogą przesyłać pliki przez Aktara, znajdować wcześniejsze przesłania i tworzyć linki. Dodajesz go agentowi raz, a on uruchamia go, gdy go potrzebuje.

Użycie

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

Opcje

FlagaWartośćOpis
--root<folder>Przesyłaj tylko pliki z tego folderu. Powtórz dla kolejnych folderów. Domyślnie: folder, w którym działa serwer, albo żaden, gdy jest to twój folder domowy lub katalog główny dysku.
--read-onlyUdostępnia tylko narzędzia, które niczego nie zmieniają w buckecie: wyszukiwanie, listy, linki tymczasowe i miniatury.
--allow-replaceUdostępnia także replace_file, które nadpisuje plik w buckecie.
--allow-deleteUdostępnia także delete_upload, które usuwa plik z jego bucketa, oraz replace_file.
--max-link-minutes<n>Jak długo najdłużej może działać link tymczasowy, w minutach. Domyślnie 60, najwyżej 10080 (7 dni).
--log<file>Dopisuj każde wywołanie narzędzia (czas, narzędzie, argumenty, wynik) do tego pliku, czytelnego tylko dla ciebie.
--port<port>Port lokalnego API Aktara, tylko dla tego polecenia. Ma pierwszeństwo przed AKTAR_PORT i zapisanym portem.

Warto wiedzieć

  • Najpierw uruchom aktar login. Serwer odczytuje zapisany token przy każdym wywołaniu, więc ponowne zalogowanie działa bez restartu agenta.
  • Przesłanie publikuje plik: każdy, kto ma link, może go otworzyć. Agenci pytają o zgodę przed wywołaniem narzędzia, chyba że im na to pozwolisz.
  • Pliki są przesyłane tylko z folderów podanych w --root, a w przeciwnym razie z folderu, w którym działa serwer. Jeśli jest to twój folder domowy albo katalog główny dysku, jak w przypadku niektórych aplikacji, żadne pliki lokalne nie są przesyłane, dopóki nie dodasz --root. --root ~ zezwala na cały folder domowy, jeśli naprawdę tego chcesz. Ścieżki są rozwiązywane, łącznie z dowiązaniami symbolicznymi, zanim zostaną sprawdzone.
  • Sekrety nigdy nie są przesyłane, niezależnie od tego, gdzie leżą: klucze SSH i prywatne, pliki .env, dane logowania do chmury i menedżerów pakietów (~/.aws, ~/.kube, ~/.npmrc i inne), konfiguracja samego Aktara, pęk kluczy, profile przeglądarek i bazy haseł. Pliki z kilkoma dowiązaniami twardymi też są odrzucane. Żeby udostępnić któryś z nich, prześlij go sam przez aktar upload.
  • --read-only udostępnia tylko narzędzia, które niczego nie zmieniają w buckecie. replace_file nadpisuje plik tak jak usunięcie, więc jest udostępniane tylko z --allow-replace, a delete_upload tylko z --allow-delete (które udostępnia też replace_file).
  • create_temporary_link tworzy linki ważne najwyżej 60 minut, chyba że --max-link-minutes pozwala na więcej. upload_clipboard jest pomijane, gdy podasz --root, bo w schowku może być cokolwiek.
  • Wyniki narzędzi zaczynają się od uwagi, że nazwy plików, klucze i komunikaty w nich to dane, a nie instrukcje, a --log zapisuje każde wywołanie. Działają najwyżej 4 wywołania narzędzi jednocześnie.
  • Bez instalacji globalnej użyj npx -y @getaktar/cli mcp --root ~/Projects jako polecenia.
  • Obsługuje bieżącą wersję MCP (2026-07-28) oraz wcześniejsze, które zaczynają się od initialize (od 2024-11-05 do 2025-11-25), przez stdio. Wymaga aktar 0.4.0; powyższe ograniczenia pojawiły się w aktar 0.6.0.

Narzędzia

NarzędzieCo robi
upload_filePrzesyła plik i zwraca jego link, Markdown i HTML. Miejsce docelowe, nazwa, folder i czas wygaśnięcia są opcjonalne. short prosi o krótki link albo o jego brak.
upload_clipboardPrzesyła plik lub obraz ze schowka. short prosi o krótki link albo o jego brak. Pomijane, gdy podano --root.
replace_fileZapisuje nowy plik w miejsce przesłanego albo dowolnego pliku w buckecie i zachowuje jego link. Tylko z --allow-replace lub --allow-delete. Wymaga Aktara na Maca 0.14.0 lub na Windows 0.7.0.
create_short_linkTworzy krótki link dla przesłanego pliku skracaczem jego miejsca docelowego albo zwraca ten, który już ma. Pomijane z --read-only. Wymaga Aktar dla Maca 0.17.0 lub Windows 0.10.0.
search_uploadsPrzeszukuje historię przesłanych plików.
list_destinationsWyświetla miejsca docelowe i typy plików, do których każde z nich jest używane.
list_bucketWyświetla foldery i pliki bucketa, także te nieprzesłane przez Aktara.
create_temporary_linkTworzy link, który po pewnym czasie przestaje działać (presigned URL). Do tego czasu każdy, kto go ma, może pobrać plik, nawet z prywatnego bucketa. Najwyżej 60 minut, chyba że --max-link-minutes pozwala na więcej.
get_thumbnailPokazuje agentowi podgląd przesłanego pliku. Wymaga Aktara na Maca 0.13.0 lub na Windows 0.6.0.
list_watched_foldersWyświetla obserwowane foldery i ich status.
get_statusSprawdza połączenie z Aktarem.
delete_uploadUsuwa przesłany plik z jego bucketa. Tylko z --allow-delete.

Przykłady

Dodaj Aktara do Claude Code lub Codex.
claude mcp add aktar -- aktar mcp --root ~/Projects
codex mcp add aktar -- aktar mcp --root ~/Projects
Agent może przesyłać z dwóch folderów i zastępować pliki.
claude mcp add aktar -- aktar mcp --root ~/Projects --root ~/Desktop --allow-replace
Zapisuj, co zrobił agent.
claude mcp add aktar -- aktar mcp --root ~/Projects --log ~/aktar-mcp.log

aktar skill

Wypisuje skill dla agentów (SKILL.md), który uczy agentów używać polecenia aktar z --json: co uruchomić, jak odczytać wynik i że mają przesyłać tylko to, co chcesz udostępnić. Dla agentów, które używają skilli, ale nie MCP.

Użycie

aktar skill

Opcje

Brak opcji.

Warto wiedzieć

  • Zapisz go tam, gdzie twój agent szuka skilli, na przykład w ~/.claude/skills/aktar/ dla Claude Code.

Przykłady

Zainstaluj skill dla Claude Code.
mkdir -p ~/.claude/skills/aktar
aktar skill > ~/.claude/skills/aktar/SKILL.md

Opcje dla każdego polecenia

FlagaWartośćOpis
-h, --helpPokaż listę poleceń i opcji.
-v, --versionPokaż wersję aktar.
--port<port>Port lokalnego API Aktara, tylko dla tego polecenia. Ma pierwszeństwo przed AKTAR_PORT i zapisanym portem.

Wyjście

Formaty

-f wybiera, co jest wypisywane dla każdego przesłanego pliku. Bez tej opcji aktar wypisuje zwykły URL, niezależnie od formatu kopiowanego przez pasek menu Aktara. Markdown i HTML osadzają obrazy, a do pozostałych plików tworzą linki, tak samo jak Aktar.

FormatWypisywane dla photo.jpg
-f urlhttps://files.example.com/2026/10/7f3c2a91.jpgLink (domyślnie).
-f markdown![](https://files.example.com/2026/10/7f3c2a91.jpg)Obraz w Markdown albo link w Markdown dla innych plików.
-f html<img src="https://files.example.com/2026/10/7f3c2a91.jpg" alt="">Znacznik <img> albo link <a> dla innych plików.
-f custom![photo.jpg](https://files.example.com/2026/10/7f3c2a91.jpg)Twój szablon z ustawień Aktara, z wypełnionymi {url}, {filename} i pozostałymi zmiennymi.

stdout i stderr

Na standardowe wyjście trafiają tylko linki, po jednym w linii, w kolejności plików (oraz kody QR, z --qr). Wszystko inne idzie na standardowe wyjście błędów: postęp, błędy i informacje takie jak aktar: photo.jpg: already uploaded, reused the existing link. Dzięki temu url=$(aktar upload file) i aktar upload *.png > links.txt zawsze dostają czyste linki.

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

JSON

--json wypisuje tablicę z jednym wpisem na każdy przesłany plik, po zakończeniu wszystkich. Nieudane przesyłania są pomijane (zgłaszane są na stderr), więc sprawdzaj też kod wyjścia.

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
  }
]
PoleZnaczenie
idID przesłanego pliku w historii Aktara. Przyjmuje je aktar qr.
filenameNazwa pliku, pod którą zna go Aktar: jego własna albo --name.
objectKeyGdzie plik znajduje się w buckecie.
urlLink.
shortUrlKrótki link albo null, gdy go nie ma. formats już go używają.
destinationIdID miejsca docelowego.
destinationNameNazwa miejsca docelowego.
mimeTypeTyp pliku, po ewentualnej konwersji przez Aktar.
sizeRozmiar w bajtach, tak jak jest przechowywany.
createdAtKiedy został przesłany (ISO 8601, UTC).
expiresAtKiedy bucket go usunie, albo null, jeśli plik zostaje.
replacedAtKiedy plik został ostatnio zastąpiony (ISO 8601, UTC). Pomijane, dopóki nie zostanie zastąpiony, oraz przez wersje Aktara starsze niż Mac 0.14.0 i Windows 0.7.0.
formatsLink we wszystkich czterech formatach: url, markdown, html i custom.
reusedtrue, gdy nic nie zostało przesłane, bo ten sam plik już tam był. Pomijane przez wersje Aktara starsze niż Mac 0.10.0 i Windows 0.3.0.
shortLinkErrorDlaczego Aktar nie mógł utworzyć krótkiego linku; url to wtedy oryginalny link. Pomijane, gdy wszystko poszło dobrze.

Kody wyjścia

KodZnaczenie
0Wszystko się udało.
1Co najmniej jedno przesyłanie lub żądanie się nie powiodło; pozostałe i tak przeszły. Tu kończą się też błędy samego Aktara, na przykład nieskonfigurowane automatyczne usuwanie.
2Nieprawidłowe argumenty, plik, który nie istnieje, albo nazwa miejsca docelowego, której Aktar nie zna. Nic nie zostało przesłane.
3Brak logowania, Aktar nie działa, jego lokalne API jest wyłączone, token jest nieprawidłowy albo aplikacja na porcie nie mogła udowodnić, że jest Aktarem (lub jest na to za stara).

Przepisy

Skopiuj, popraw nazwy plików, gotowe. Każdy przepis korzysta tylko z tego, co opisano powyżej.

Link w zmiennej

Na standardowe wyjście trafia tylko link, więc podstawienie polecenia dostaje dokładnie URL. || exit 1 zatrzymuje skrypt, jeśli przesyłanie się nie powiodło.

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

Prześlij build i opublikuj link

Spakuj build do ZIP, prześlij go do miejsca docelowego o nazwie Builds pod krótkim hashem commita i wyślij link do dowolnego webhooka przyjmującego JSON (kanału czatu, systemu zgłoszeń, własnego endpointu). set -e zatrzymuje skrypt przed wysłaniem, jeśli przesyłanie się nie powiedzie.

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

Cel w Makefile

make share przesyła raport pod dzisiejszą datą i zapisuje link w .last-link. W Makefile $$ przekazuje powłoce $, a linia polecenia zaczyna się od tabulatora.

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

Przesyłanie obrazów w Typorze

W Typorze otwórz Settings > Image, wybierz Custom Command jako image uploader i wpisz pełną ścieżkę do aktar (tę, którą wypisuje which aktar), a po niej upload. Typora przekazuje ścieżki obrazów i odczytuje jeden link na linię.

/opt/homebrew/bin/aktar upload

Krok po kroku, z ustawieniem When Insert…: Przesyłanie obrazów z Typory do S3.

Przesyłanie z Findera lub Skrótów

Na Macu dodaj czynność Uruchom skrypt powłoki do skrótu albo do szybkiej czynności Automatora, która odbiera pliki w Finderze, i ustaw przekazywanie wejścia jako argumenty. Skróty i Automator nie wczytują zmiennej PATH twojej powłoki, stąd pierwsza linia. Zaznacz pliki, uruchom, a linki będą w schowku.

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

Przesyła pliki, nie foldery. Kilka plików daje kilka linków, po jednym w linii.

Pliki tymczasowe

Log, nagranie ekranu albo cokolwiek, co nie powinno zostać na dłużej, niech usunie bucket. Miejsce docelowe potrzebuje najpierw reguł automatycznego usuwania Aktara: skonfiguruj je raz przez Usuń po na pasku menu Aktara albo w ustawieniach miejsca docelowego.

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

Wygasające pliki trafiają do tmp/1d/, tmp/7d/ i tak dalej w buckecie, a bucket usuwa je nawet wtedy, gdy Aktar nie działa.

Otwórz link na telefonie

--qr wypisuje kod QR pod linkiem; skieruj aparat telefonu na terminal. Aby pokazać go później ponownie, podaj ID przesłanego pliku poleceniu aktar qr, tutaj najnowszego pliku pasującego do „demo”.

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

Windows PowerShell

To samo działa w PowerShellu. $LASTEXITCODE zawiera kod wyjścia, a ConvertFrom-Json odczytuje --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 w Claude Desktop, Cursor lub VS Code

Aplikacje, które przyjmują konfigurację JSON dla serwerów MCP (Claude Desktop, Cursor, Windsurf i inne), potrzebują tego wpisu. VS Code używa tego samego wpisu w servers w pliku .vscode/mcp.json. Potem poproś agenta, żeby przesłał plik, znalazł zrzuty ekranu z zeszłego tygodnia albo utworzył link tymczasowy.

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

Jeśli aplikacja nie może znaleźć aktar, użyj jego pełnej ścieżki (which aktar) albo npx z argumentami ["-y", "@getaktar/cli", "mcp", "--root", "/Users/you/Projects"]. Po --root wpisz folder, z którego agent może przesyłać pliki (na Windows na przykład C:\\Users\\you\\Projects).

Co Aktar robi za ciebie

CLI tylko przekazuje pliki; resztę robi Aktar, z ustawieniami każdego miejsca docelowego. Wszystko, co skonfigurowałeś w aplikacji, działa więc też dla aktar upload, bez dodatkowych opcji, a link, który dostajesz, prowadzi do pliku w takiej postaci, w jakiej został zapisany.

  • Szablony ścieżek

    Ścieżka obiektu miejsca docelowego nadaje plikowi nazwę, z {year}, {uuid}, {filename} i pozostałymi zmiennymi. {md5} i {sha256} nazywają pliki według ich zawartości.

  • Przetwarzanie obrazów

    Jeśli miejsce docelowe konwertuje obrazy do WebP lub AVIF, kompresuje je albo zmienia ich rozmiar, pliki przesłane przez CLI są traktowane tak samo, a link prowadzi do przekonwertowanego pliku.

  • Metadane zdjęć

    Metadane obrazów w domyślnych ustawieniach przesyłania miejsca docelowego usuwają ze zdjęć lokalizację albo wszystkie metadane, zanim opuszczą one twój komputer.

  • Ten sam plik, ten sam link

    Gdy włączona jest opcja Używaj ponownie linków dla zduplikowanych plików, ta sama zawartość w tym samym miejscu docelowym dostaje istniejący link zamiast ponownego przesłania. aktar informuje o tym na stderr.

  • Duże pliki

    Duże pliki są przesyłane w częściach, bez limitu 5 GB, ponawiane po zerwaniu połączenia i wznawiane od miejsca, w którym przerwano. aktar przesyła plik do Aktara strumieniowo, więc nigdy nie wczytuje go do pamięci.

  • Linki publiczne lub tymczasowe

    To, czy link jest publiczny, czy tymczasowy (presigned), działający także dla prywatnego bucketu, zależy od miejsca docelowego, tak jak w aplikacji.

Linki dla duplikatów, przetwarzanie obrazów, {md5} i {sha256} oraz przesyłanie w częściach pojawiły się w Aktarze dla Maca 0.10.0 i Windows 0.3.0: co nowego w 0.10.0.

Rozwiązywanie problemów

Komunikaty o błędach aktar zaczynają się od aktar: i trafiają na stderr. Kod wyjścia mówi, jakiego rodzaju jest problem.

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

Otwórz Aktar i sprawdź, czy opcja Zezwalaj na połączenia lokalne jest włączona w Ustawienia > Integracje. Jeśli zmieniłeś tam port, podaj go przez --port lub AKTAR_PORT albo uruchom ponownie aktar login --port. Kod wyjścia 3.

Not connected to Aktar yet

Nie ma zapisanego tokenu ani AKTAR_TOKEN. Uruchom aktar login z tokenem z Ustawienia > Integracje w Aktarze. Kod wyjścia 3.

The token doesn't match Aktar's anymore

Token został wygenerowany ponownie w Aktarze albo jest błędnie wpisany. Uruchom ponownie aktar login z aktualnym tokenem. Jeśli ustawiony jest AKTAR_TOKEN, ma on pierwszeństwo przed zapisanym tokenem, więc zaktualizuj go albo usuń. Kod wyjścia 3.

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

Coś odpowiedziało na porcie Aktara, ale nie mogło wykazać, że ma twój token, więc token nie został wysłany. Jeśli Aktar działa, jego token prawdopodobnie się zmienił: uruchom ponownie aktar login. Jeśli Aktar nie działa, otwórz go. Kod wyjścia 3.

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

aktar 0.6.0 i nowsze sprawdzają aplikację przed wysłaniem tokenu, co wymaga Aktara dla Maca 0.18.0 lub Aktara dla Windows 0.11.0 albo nowszego. Zaktualizuj Aktara (sam proponuje aktualizacje), a polecenie znów zadziała. Kod wyjścia 3.

MCP: This server doesn't upload local files

Agent uruchomił aktar mcp w twoim folderze domowym albo w katalogu głównym dysku i nie ma --root. Dodaj --root z folderem, z którego mogą pochodzić pliki, do polecenia lub konfiguracji serwera, na przykład aktar mcp --root ~/Projects, i uruchom agenta ponownie.

Auto-delete isn't set up for this destination

--expires wymaga reguł automatycznego usuwania w buckecie. Skonfiguruj je raz przez Usuń po na pasku menu Aktara albo w ustawieniach miejsca docelowego, albo prześlij plik bez --expires. Kod wyjścia 1.

No destination named "…"

Komunikat wymienia nazwy, które zna Aktar. Sprawdź pisownię, nazwy ze spacjami ujmij w cudzysłów (-d "Client work") albo użyj ID z aktar destinations. Kod wyjścia 2.

Duże przesyłanie trwa długo

To kwestia szybkości dostawcy magazynu: aktar nie ma limitu czasu na przesyłanie i w terminalu pokazuje postęp na stderr. Nie zamykaj Aktara, dopóki się nie skończy. Jeśli połączenie zostanie zerwane albo Aktar się zamknie (Aktar closed the connection before the request finished), prześlij ten sam plik ponownie: Aktar dla Maca 0.10.0 i Windows 0.3.0 wznawia od ostatniej części.

aktar się nie uruchamia: SyntaxError lub parseArgs

Twój Node.js jest starszy niż 18. Sprawdź to przez node --version i zaktualizuj go albo zainstaluj aktar przez Homebrew, który dostarcza własny Node.js.

PowerShell zgłasza, że uruchamianie skryptów jest wyłączone

Zasady wykonywania PowerShella blokują skrypt, który npm instaluje dla aktar. Uruchom zamiast tego aktar.cmd albo raz zezwól na lokalne skrypty przez Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.