Dokumentacja aktar CLI: polecenia, opcje, JSON i przepisy

Q: 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.

Q: 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.

Q: 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.

Q: 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.

Q: 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.

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.4.0 lub nowszy albo Aktar dla Windows, z co najmniej jednym miejscem docelowym
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

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.3.0

Połączenie z Aktarem

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.
Skopiuj token wyświetlony pod spodem.
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ć.

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

Zmienna	Do czego służy
`AKTAR_TOKEN`	Token z Ustawienia > Integracje w Aktarze. Używany zamiast zapisanego.
`AKTAR_PORT`	Port lokalnego API Aktara, jeśli go zmieniłeś. `--port` ma przed nim pierwszeństwo.
`NO_COLOR`	Rysuje kody QR zwykłymi znakami zamiast kolorami terminala.
`XDG_CONFIG_HOME`	Lokalizacja 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
aktar upload --clipboard
aktar replace
aktar qr
aktar login
aktar logout
aktar status
aktar destinations
aktar history

`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

Flaga	Wartość	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.
`--qr`		Wypisz też kod QR każdego linku.
`--json`		Wypisz 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.

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

`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

Flaga	Wartość	Opis
`--clipboard`		Prześ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.
`--qr`		Wypisz też kod QR każdego linku.
`--json`		Wypisz 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

Flaga	Wartość	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).
`--qr`		Wypisz też kod QR każdego linku.
`--json`		Wypisz 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 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

Flaga	Wartość	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ć.

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

Flaga	Wartość	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 token trafia do historii powłoki. 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 login --token "$AKTAR_SECRET" --port 47920
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

Flaga	Wartość	Opis
`--json`		Wypisz 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

Flaga	Wartość	Opis
`--json`		Wypisz 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

Flaga	Wartość	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.
`--json`		Wypisz 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

Opcje dla każdego polecenia

Flaga	Wartość	Opis
`-h, --help`		Pokaż listę poleceń i opcji.
`-v, --version`		Pokaż 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.

Format	Wypisywane dla photo.jpg
`-f url`	`https://files.example.com/2026/10/7f3c2a91.jpg`Link (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",
    "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
  }
]

Pole	Znaczenie
`id`	ID przesłanego pliku w historii Aktara. Przyjmuje je `aktar qr`.
`filename`	Nazwa pliku, pod którą zna go Aktar: jego własna albo `--name`.
`objectKey`	Gdzie plik znajduje się w buckecie.
`url`	Link.
`destinationId`	ID miejsca docelowego.
`destinationName`	Nazwa miejsca docelowego.
`mimeType`	Typ pliku, po ewentualnej konwersji przez Aktar.
`size`	Rozmiar w bajtach, tak jak jest przechowywany.
`createdAt`	Kiedy został przesłany (ISO 8601, UTC).
`expiresAt`	Kiedy bucket go usunie, albo `null`, jeśli plik zostaje.
`replacedAt`	Kiedy 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.
`formats`	Link we wszystkich czterech formatach: `url`, `markdown`, `html` i `custom`.
`reused`	`true`, 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.

Kody wyjścia

Kod	Znaczenie
`0`	Wszystko się udało.
`1`	Co 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.
`2`	Nieprawidłowe argumenty, plik, który nie istnieje, albo nazwa miejsca docelowego, której Aktar nie zna. Nic nie zostało przesłane.
`3`	Brak logowania, Aktar nie działa, jego lokalne API jest wyłączone albo token jest nieprawidłowy.

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

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.

`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.

Dokumentacja aktar CLI

Czym jest

Czym nie jest

Wymagania

Gdzie przechowywany jest token

Skrypty i CI

Opcje dla każdego polecenia

Formaty

stdout i stderr

JSON

Kody wyjścia

Szablony ścieżek

Przetwarzanie obrazów

Metadane zdjęć

Ten sam plik, ten sam link

Duże pliki

Linki publiczne lub tymczasowe

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

Not connected to Aktar yet

The token doesn't match Aktar's anymore

Auto-delete isn't set up for this destination

No destination named "…"

Duże przesyłanie trwa długo

aktar się nie uruchamia: SyntaxError lub parseArgs

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

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

`Not connected to Aktar yet`

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

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

`No destination named "…"`

`aktar` się nie uruchamia: `SyntaxError` lub `parseArgs`