• Aktar CLI

Documentazione della CLI aktar

Ogni comando, opzione e output di aktar, con esempi da copiare e incollare. Prima volta qui? La panoramica della CLI si legge più in fretta.

Panoramica della CLI

Panoramica

aktar è un telecomando per l'app Aktar sullo stesso computer. Gli passi dei file, lui li inoltra ad Aktar su 127.0.0.1 e Aktar li carica con le destinazioni, le chiavi, i modelli di percorso e le impostazioni dei link che hai già configurato. Il link torna nel tuo terminale.

Cos'è

  • Un piccolo comando Node.js per script, job di CI sul tuo Mac o PC Windows ed editor come Typora
  • Un modo per caricare file e il contenuto degli Appunti, mostrare codici QR e leggere le tue destinazioni e la cronologia dei caricamenti
  • Gratuito e open source (MIT), come l'app

Cosa non è

  • Non è autonomo: senza Aktar in esecuzione non può caricare nulla. Non conserva mai le chiavi del tuo storage
  • Non è pensato per server Linux o macchine remote: parla solo con Aktar sullo stesso computer. Lì usa la CLI del tuo provider di storage

Requisiti

  • Aktar per Mac 0.18.0 o Aktar per Windows 0.11.0 o successivo, con almeno una destinazione. aktar 0.5.0 e precedenti funzionano con Aktar per Mac 0.4.0 o successivo
  • Node.js 18 o successivo (Homebrew lo installa per te)
  • --name, --qr e aktar qr richiedono aktar 0.2.0 o successivo
  • Riutilizzare il link di un file già caricato richiede aktar 0.2.0 e Aktar per Mac 0.10.0 o Aktar per Windows 0.3.0
  • aktar replace richiede aktar 0.3.0 e Aktar per Mac 0.14.0 o Aktar per Windows 0.7.0 o successivo
  • --short, --no-short e aktar short richiedono aktar 0.5.0 e Aktar per Mac 0.17.0 o Aktar per Windows 0.10.0, con un accorciatore configurato sulla destinazione

Installazione

Installalo una volta, con npm o Homebrew. Entrambi aggiungono il comando aktar al tuo path.

Con npm (macOS e Windows)

npm install -g @getaktar/cli

Con Homebrew (macOS)

brew install getaktar/tap/aktar-cli

Oppure eseguilo una volta senza installare niente:

npx @getaktar/cli upload file.png

Controlla quale versione hai:

aktar --version
0.6.0

Connessione ad Aktar

  1. In Aktar per Mac o Windows, apri Impostazioni > Integrazioni e attiva Consenti connessioni locali. Da quel momento Aktar ascolta solo su 127.0.0.1, sulla porta 47913 se non la cambi lì.
  2. Copia il token che compare sotto.
  3. Esegui aktar login e incolla il token al prompt Token:. Resta nascosto mentre digiti e viene verificato con Aktar prima di essere salvato, così un errore di battitura non finisce in memoria.
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

Dove viene salvato il token

aktar login salva token e porta in ~/.config/aktar/cli.json su Mac (o in $XDG_CONFIG_HOME/aktar/cli.json se l'hai impostata) e in %APPDATA%\aktar\cli.json su Windows. Solo il tuo utente può leggerlo.

Prima di inviare il token, aktar chiede all'app sulla porta di dimostrare che ha lo stesso token, senza inviarlo. Così, se Aktar non è in esecuzione e un altro programma è in ascolto sulla sua porta, quel programma non riceve né il token né i tuoi file. Serve Aktar per Mac 0.18.0 o Aktar per Windows 0.11.0 o successivo; con un Aktar più vecchio, aktar si ferma e ti chiede di aggiornarlo.

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

aktar logout elimina quel file. Per escludere tutti i client in un colpo solo, fai clic su Rigenera accanto al token in Aktar, poi esegui di nuovo aktar login con quello nuovo.

Script e CI

Su una macchina di build salta aktar login e imposta AKTAR_TOKEN (e AKTAR_PORT se hai cambiato la porta). Hanno la precedenza sul file salvato. Aktar deve essere in esecuzione su quella macchina, nella stessa sessione utente.

AKTAR_TOKEN="$AKTAR_SECRET" aktar upload dist/app.zip -d Builds
VariabileA cosa serve
AKTAR_TOKENIl token da Impostazioni > Integrazioni di Aktar. Viene usato al posto di quello salvato.
AKTAR_PORTLa porta dell'API locale di Aktar, se l'hai cambiata. --port ha la precedenza.
NO_COLORDisegna i codici QR con caratteri semplici invece dei colori del terminale.
XDG_CONFIG_HOMEDove si trova la cartella di configurazione su macOS (predefinita ~/.config). Su Windows si usa %APPDATA%.

Comandi

Tutti i comandi parlano con Aktar, tranne aktar qr con testo semplice o un link. Senza -d, i caricamenti vanno alla destinazione selezionata nella barra dei menu di Aktar e compaiono nella cronologia di Aktar come tutti gli altri. aktar --help stampa lo stesso elenco. Con Aktar per Mac 0.14.0 o Aktar per Windows 0.7.0 o successivo, un caricamento senza -d segue prima le regole Usa per delle destinazioni, così un'immagine può finire nella destinazione degli screenshot e una build in un'altra.

aktar upload

Carica uno o più file e stampa un link per file, in ordine, man mano che ciascuno finisce.

Uso

aktar upload <file>... [options]

Opzioni

FlagValoreDescrizione
-d, --destination<name|id>Destinazione su cui caricare, per nome o ID. Predefinita: quella selezionata in Aktar.
-f, --format<format>Cosa stampare: url (predefinito), markdown, html o custom (il tuo modello in Aktar).
--name<name>Carica un file con questo nome. Se il nome non ha estensione, viene mantenuta quella del file.
--folder<path>Mantieni il nome del file e caricalo in questa cartella.
--expires<days>Fai eliminare il file dal bucket dopo 1, 7, 14 o 30 giorni. 0 lo conserva.
--shortCrea un link breve con l'accorciatore della destinazione, anche se le sue regole salterebbero questo caricamento.
--no-shortNon creare un link breve questa volta.
--qrStampa anche un codice QR per ogni link.
--jsonStampa un array JSON con tutti i dettagli di ogni caricamento, invece dei link.
--port<port>La porta dell'API locale di Aktar, solo per questo comando. Ha la precedenza su AKTAR_PORT e sulla porta salvata.

Buono a sapersi

  • Tutti i file vengono controllati prima di caricare qualsiasi cosa: se uno non esiste, non viene caricato nulla e aktar esce con codice 2.
  • Se un caricamento non riesce, gli altri vanno comunque a buon fine. Ogni errore viene segnalato su stderr e il codice di uscita è 1.
  • Senza --folder, il nome del file lo decide il modello di percorso della destinazione, proprio come quando trascini un file sulla barra dei menu. Con --folder, il file mantiene il suo nome dentro quella cartella.
  • --name funziona con un file alla volta. Le barre vengono rimosse e, se il nome non ha estensione, viene aggiunta quella del file: --name cover carica IMG_4021.jpg come cover.jpg. Con --folder, è il nome dentro la cartella.
  • --expires accetta 1, 7, 14 o 30 (giorni), oppure 0 per conservare il file. Senza questa opzione il file viene conservato, qualunque sia il valore di Elimina dopo in Aktar. Richiede le regole di eliminazione automatica di Aktar su quella destinazione e non si può combinare con --folder.
  • --qr non si può combinare con --json, e --png funziona solo con aktar qr.
  • In un terminale, l'avanzamento compare su stderr durante il caricamento. Il file viene inviato ad Aktar in streaming, quindi la dimensione non conta e non c'è limite di tempo.
  • Se la destinazione ha un accorciatore configurato in Aktar, viene stampato il link breve, e --format e --qr lo usano. --short ne crea uno anche se le regole della destinazione salterebbero questo caricamento, --no-short non ne crea nessuno. Se Aktar non riesce a crearlo, viene stampato il link originale e stderr spiega perché.

Esempi

Un file, un link.
aktar upload screenshot.png
https://files.example.com/2026/10/7f3c2a91.png
Più file, in Markdown: una riga per file, in ordine.
aktar upload *.png -f markdown
![](https://files.example.com/2026/10/1b9e44d0.png)
![](https://files.example.com/2026/10/c2f71a5e.png)
Carica con un altro nome, dentro una cartella.
aktar upload IMG_4021.jpg --name cover --folder blog/2026
https://files.example.com/blog/2026/cover.jpg
Lo stesso file era già nel bucket: il link viene stampato come sempre e la nota va su stderr.
aktar upload photo.jpg
aktar: photo.jpg: already uploaded, reused the existing link
https://files.example.com/2026/09/4d2a8c61.jpg
Con un accorciatore sulla destinazione, viene stampato il link breve.
aktar upload talk.pdf --short
https://s.example.com/k3Tq9

aktar upload --clipboard

Carica il file o l'immagine negli Appunti, come la scorciatoia per gli Appunti di Aktar.

Uso

aktar upload --clipboard [options]

Opzioni

FlagValoreDescrizione
--clipboardCarica il contenuto degli Appunti invece dei file.
-d, --destination<name|id>Destinazione su cui caricare, per nome o ID. Predefinita: quella selezionata in Aktar.
-f, --format<format>Cosa stampare: url (predefinito), markdown, html o custom (il tuo modello in Aktar).
--expires<days>Fai eliminare il file dal bucket dopo 1, 7, 14 o 30 giorni. 0 lo conserva.
--shortCrea un link breve con l'accorciatore della destinazione, anche se le sue regole salterebbero questo caricamento.
--no-shortNon creare un link breve questa volta.
--qrStampa anche un codice QR per ogni link.
--jsonStampa un array JSON con tutti i dettagli di ogni caricamento, invece dei link.
--port<port>La porta dell'API locale di Aktar, solo per questo comando. Ha la precedenza su AKTAR_PORT e sulla porta salvata.

Buono a sapersi

  • Passa dei file oppure --clipboard, non entrambi.
  • --name e --folder funzionano solo con i file. -d, -f, --expires, --qr e --json funzionano come con i file.
  • Con --json stampa comunque un array, con una sola voce.

Esempi

Lo screenshot che hai appena copiato.
aktar upload --clipboard
https://files.example.com/2026/10/9a4c03be.png
In Markdown, su una destinazione chiamata Blog.
aktar upload --clipboard -f markdown -d Blog
![](https://blog-assets.example.com/2026/10/e5b2c8a4.png)
Eliminato dal bucket dopo un giorno.
aktar upload --clipboard --expires 1
https://files.example.com/tmp/1d/2026/10/38f0d7c2.png

aktar replace

Scrive un nuovo file al posto di un caricamento, così chiave e link restano gli stessi. Chiunque abbia il link vede il nuovo file.

Uso

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

Opzioni

FlagValoreDescrizione
-d, --destination<name|id>Per una chiave: la destinazione nel cui bucket si trova, per nome o ID. Predefinita: quella selezionata in Aktar.
-f, --format<format>Cosa stampare: url (predefinito), markdown, html o custom (il tuo modello in Aktar).
--qrStampa anche un codice QR per ogni link.
--jsonStampa un array JSON con tutti i dettagli di ogni caricamento, invece dei link.
--port<port>La porta dell'API locale di Aktar, solo per questo comando. Ha la precedenza su AKTAR_PORT e sulla porta salvata.

Buono a sapersi

  • Il primo argomento è un ID di caricamento o un link da aktar history (la voce nella cronologia di Aktar viene aggiornata), altrimenti una chiave nel bucket di -d (la destinazione selezionata in Aktar, se lo ometti). Un link che non è nella cronologia di Aktar viene rifiutato: passa invece la sua chiave con -d.
  • Aktar rimuove i metadati del file e lo ridimensiona come indicato dalla destinazione, ma non lo converte mai in un altro formato, quindi l'estensione della chiave resta. Un file sotto tmp/{N}d/ ricomincia il conto dei suoi N giorni.
  • La chiave non viene mai numerata e non viene caricato nient'altro. --folder, --expires, --name e --clipboard non si applicano e vengono rifiutati.
  • Le copie vecchie possono restare per un po' nella cache di una CDN. L'opzione Cache breve di una destinazione o lo svuotamento della cache di Cloudflare in Aktar risolvono il problema.
  • Richiede Aktar per Mac 0.14.0 o Aktar per Windows 0.7.0 o successivo.

Esempi

Sostituisci un caricamento della cronologia tramite il suo ID; il link resta lo stesso.
aktar replace 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 report-v2.pdf
https://files.example.com/2026/09/0e7d51b3.pdf
Sostituisci una chiave nel bucket di un'altra destinazione e stampala in Markdown.
aktar replace docs/guide.pdf guide.pdf -d Blog -f markdown
[guide.pdf](https://blog-assets.example.com/docs/guide.pdf)

aktar short

Crea un link breve per un caricamento della cronologia con l'accorciatore della sua destinazione e lo stampa. Se il caricamento ne ha già uno, stampa quello.

Uso

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

Opzioni

FlagValoreDescrizione
--jsonStampa i dettagli del link breve in JSON: provider, stato e clic.
--qrStampa anche il codice QR del link breve.
--port<port>La porta dell'API locale di Aktar, solo per questo comando. Ha la precedenza su AKTAR_PORT e sulla porta salvata.

Buono a sapersi

  • Passa un ID di caricamento o un link di aktar history; va bene anche il suo link breve. aktar lo cerca negli ultimi 1.000 caricamenti.
  • La destinazione deve avere un accorciatore nella sezione Link brevi di Aktar: Shlink, YOURLS, Kutt, Dub, Short.io o una richiesta personalizzata. Il link breve viene da quell'accorciatore, quindi i tuoi link e i dati dei clic restano nella tua infrastruttura.
  • --json stampa i dettagli del link breve: provider, stato, e clic e ultimo clic se l'accorciatore li conta. --qr aggiunge il suo codice QR. Le due opzioni non si possono combinare.
  • Richiede Aktar per Mac 0.17.0 o Aktar per Windows 0.10.0. Le versioni precedenti rispondono che non creano ancora link brevi.

Esempi

Un link breve per un caricamento della cronologia.
aktar short 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1
https://s.example.com/Qm3xZ

aktar qr

Mostra nel terminale il codice QR di un link o di qualsiasi testo, così puoi aprirlo sul telefono. Con un ID di caricamento, mostra il link di quel caricamento e il suo codice QR.

Uso

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

Opzioni

FlagValoreDescrizione
--png<file>Salva il codice QR come file PNG invece di stamparlo.
--port<port>La porta dell'API locale di Aktar, solo per questo comando. Ha la precedenza su AKTAR_PORT e sulla porta salvata.

Buono a sapersi

  • Passa esattamente un argomento e metti tra virgolette il testo con spazi.
  • Un ID di caricamento è l'id di aktar history --json o aktar upload --json. aktar lo cerca tra gli ultimi 1.000 caricamenti nella cronologia di Aktar; per testo semplice o un link, Aktar non serve affatto.
  • In un terminale il codice viene disegnato nero su bianco, qualunque sia il tema. Se l'output non è un terminale, o se NO_COLOR è impostata, viene disegnato senza colori.
  • --png salva il codice QR come PNG invece di stamparlo.
  • Per un caricamento con un link breve, mostra il link breve.

Esempi

Un codice QR per qualsiasi link. La fotocamera del telefono lo apre.
aktar qr https://files.example.com/2026/10/demo.mp4
Un caricamento della cronologia, salvato come PNG.
aktar qr 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 --png cover-qr.png
Saved to cover-qr.png

aktar login

Verifica un token con Aktar e lo salva, così gli altri comandi possono connettersi.

Uso

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

Opzioni

FlagValoreDescrizione
--token<token>Il token, al posto del prompt.
--port<port>La porta di Aktar, salvata insieme al token. Predefinita 47913.

Buono a sapersi

  • In un terminale chiede il token e nasconde quello che digiti. Se l'input arriva da una pipe, legge il token da lì.
  • --token salta il prompt, ma altri programmi possono vedere il token mentre il comando è in esecuzione e finisce nella cronologia della shell, quindi aktar ti avvisa. Passarlo con una pipe o usare AKTAR_TOKEN lo evita.
  • Un token rifiutato da Aktar non viene salvato e il codice di uscita è 3.

Esempi

Il token resta nascosto mentre lo digiti.
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
Su Mac, con il token copiato da Aktar.
pbpaste | aktar login
Connected to Aktar 0.10.0. Saved to /Users/you/.config/aktar/cli.json
Senza prompt, per una porta modificata. aktar avvisa che il token era visibile.
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

Elimina il token e la porta salvati.

Uso

aktar logout

Opzioni

Nessuna opzione.

Buono a sapersi

  • AKTAR_TOKEN, se impostata, continua a funzionare dopo aktar logout.
  • Non disconnette gli altri client. Per quello, rigenera il token in Aktar.

Esempi

Dimentica il token.
aktar logout
Logged out.
Dopo, i comandi ti chiedono di accedere di nuovo (codice di uscita 3).
aktar status
aktar: Not connected to Aktar yet. Run aktar login with the token from Aktar's Settings > Integrations.

aktar status

Mostra a quale Aktar sei connesso, su quale porta, la destinazione selezionata in Aktar e dove si trova il file di configurazione.

Uso

aktar status [--json]

Opzioni

FlagValoreDescrizione
--jsonStampa JSON invece di testo.
--port<port>La porta dell'API locale di Aktar, solo per questo comando. Ha la precedenza su AKTAR_PORT e sulla porta salvata.

Buono a sapersi

  • Un modo rapido per controllare la connessione in uno script: esce con codice 3 quando Aktar non è raggiungibile o il token è sbagliato.

Esempi

Connesso, con la destinazione selezionata.
aktar status
Aktar 0.10.0 (build 28) on port 47913
Destination: Screenshots (Cloudflare R2, screenshots)
Config: /Users/you/.config/aktar/cli.json
Lo stesso in JSON, per gli script.
aktar status --json
{
  "app": "Aktar",
  "version": "0.10.0",
  "build": "28",
  "apiVersion": 1,
  "defaultDestinationId": "5D1A9C3E-7B2F-4E61-8A0D-3C9B6F2E1A47",
  "outputFormat": "url",
  "port": 47913
}

aktar destinations

Elenca le tue destinazioni con provider, bucket e ID. * indica quella selezionata in Aktar.

Uso

aktar destinations [--json]

Opzioni

FlagValoreDescrizione
--jsonStampa JSON invece di testo.
--port<port>La porta dell'API locale di Aktar, solo per questo comando. Ha la precedenza su AKTAR_PORT e sulla porta salvata.

Buono a sapersi

  • Usa un nome o un ID con -d. I nomi vengono confrontati senza distinguere maiuscole e minuscole; un ID funziona sempre, anche dopo una rinomina.
  • --json restituisce id, name, provider, providerName, bucket, publicBaseURL e isDefault per ciascuna.

Esempi

La destinazione selezionata è indicata con *.
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
Il nome della destinazione selezionata, con jq.
aktar destinations --json | jq -r '.[] | select(.isDefault) | .name'
Screenshots

aktar history

Elenca i caricamenti recenti, dal più nuovo: data, nome del file e link. Le parole dopo history cercano nella cronologia.

Uso

aktar history [search] [options]

Opzioni

FlagValoreDescrizione
-n, --limit<n>Quanti caricamenti elencare. Predefinito 20.
-d, --destination<name|id>Solo i caricamenti su questa destinazione, per nome o ID.
--jsonStampa JSON invece di testo.
--port<port>La porta dell'API locale di Aktar, solo per questo comando. Ha la precedenza su AKTAR_PORT e sulla porta salvata.

Buono a sapersi

  • Elenca 20 caricamenti, a meno che tu non passi -n.
  • --json restituisce gli stessi campi di aktar upload --json, compreso l'id di ogni caricamento per aktar qr.

Esempi

Gli ultimi tre caricamenti.
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
Cerca le fatture in una destinazione.
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
Il link dell'ultima build, con 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

Avvia un server Model Context Protocol (MCP), così gli agenti AI come Claude, Cursor, VS Code e Codex possono caricare file tramite Aktar, trovare i caricamenti passati e creare link. Lo aggiungi una sola volta al tuo agente, che lo avvia quando serve.

Uso

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

Opzioni

FlagValoreDescrizione
--root<folder>Carica solo file da questa cartella. Ripeti per altre cartelle. Predefinito: la cartella in cui viene eseguito il server, o nessuna se è la tua cartella Inizio o la radice del disco.
--read-onlyOffre solo gli strumenti che non modificano nulla in un bucket: ricerca, elenchi, link temporanei e miniature.
--allow-replaceOffre anche replace_file, che sovrascrive un file in un bucket.
--allow-deleteOffre anche delete_upload, che elimina un file dal suo bucket, e replace_file.
--max-link-minutes<n>La durata massima di un link temporaneo, in minuti. Predefinita 60, al massimo 10080 (7 giorni).
--log<file>Aggiunge ogni chiamata di strumento (ora, strumento, argomenti, risultato) a questo file, leggibile solo da te.
--port<port>La porta dell'API locale di Aktar, solo per questo comando. Ha la precedenza su AKTAR_PORT e sulla porta salvata.

Buono a sapersi

  • Esegui prima aktar login. Il server legge il token salvato a ogni chiamata, quindi accedere di nuovo funziona senza riavviare l'agente.
  • Caricare un file lo pubblica: chiunque abbia il link può aprirlo. Gli agenti chiedono conferma prima di chiamare uno strumento, a meno che tu non lo consenta.
  • I file vengono caricati solo dalle cartelle che indichi con --root, altrimenti dalla cartella in cui viene eseguito il server. Se è la tua cartella Inizio o la radice del disco, come succede con alcune app, nessun file locale viene caricato finché non aggiungi --root. --root ~ consente tutta la tua cartella Inizio, se lo vuoi davvero. I percorsi vengono risolti, collegamenti simbolici compresi, prima di essere controllati.
  • I segreti non vengono mai caricati, ovunque si trovino: chiavi SSH e private, file .env, credenziali di cloud e gestori di pacchetti (~/.aws, ~/.kube, ~/.npmrc e altri), la configurazione di Aktar stesso, il Portachiavi, i profili del browser e i database di password. Vengono rifiutati anche i file con più hard link. Per condividerne uno, caricalo tu con aktar upload.
  • --read-only offre solo gli strumenti che non modificano nulla in un bucket. replace_file sovrascrive un file come farebbe un'eliminazione, quindi è offerto solo con --allow-replace, e delete_upload solo con --allow-delete (che offre anche replace_file).
  • create_temporary_link crea link di al massimo 60 minuti, a meno che --max-link-minutes non ne consenta di più. upload_clipboard è escluso quando indichi --root, perché gli appunti possono contenere qualsiasi cosa.
  • I risultati degli strumenti iniziano con una nota che dice che nomi di file, chiavi e messaggi al loro interno sono dati, non istruzioni, e --log tiene traccia di ogni chiamata. Esegue al massimo 4 chiamate di strumenti alla volta.
  • Senza un'installazione globale, usa npx -y @getaktar/cli mcp --root ~/Projects come comando.
  • Supporta la versione MCP attuale (2026-07-28) e le precedenti che iniziano con initialize (da 2024-11-05 a 2025-11-25), tramite stdio. Richiede aktar 0.4.0; i limiti descritti sopra sono arrivati con aktar 0.6.0.

Strumenti

StrumentoCosa fa
upload_fileCarica un file e restituisce il suo link, Markdown e HTML. Destinazione, nome, cartella e scadenza sono facoltativi. short chiede un link breve, o nessuno.
upload_clipboardCarica il file o l'immagine negli appunti. short chiede un link breve, o nessuno. Escluso quando è indicato --root.
replace_fileScrive un nuovo file al posto di un caricamento o di qualsiasi file in un bucket, mantenendone il link. Solo con --allow-replace o --allow-delete. Richiede Aktar per Mac 0.14.0 o Windows 0.7.0.
create_short_linkCrea un link breve per un caricamento con l'accorciatore della sua destinazione, o restituisce quello che ha già. Escluso con --read-only. Richiede Aktar per Mac 0.17.0 o Windows 0.10.0.
search_uploadsCerca nella cronologia dei caricamenti.
list_destinationsElenca le destinazioni e i tipi di file per cui è usata ciascuna.
list_bucketElenca le cartelle e i file di un bucket, compresi quelli non caricati con Aktar.
create_temporary_linkCrea un link che smette di funzionare dopo un po' (un URL presigned). Fino ad allora chiunque lo abbia può scaricare il file, anche da un bucket privato. Al massimo 60 minuti, a meno che --max-link-minutes non consenta di più.
get_thumbnailMostra all'agente un'anteprima di un caricamento. Richiede Aktar per Mac 0.13.0 o Windows 0.6.0.
list_watched_foldersElenca le cartelle monitorate e il loro stato.
get_statusControlla la connessione ad Aktar.
delete_uploadElimina un caricamento dal suo bucket. Solo con --allow-delete.

Esempi

Aggiungi Aktar a Claude Code o Codex.
claude mcp add aktar -- aktar mcp --root ~/Projects
codex mcp add aktar -- aktar mcp --root ~/Projects
L'agente può caricare da due cartelle e sostituire file.
claude mcp add aktar -- aktar mcp --root ~/Projects --root ~/Desktop --allow-replace
Tiene traccia di ciò che ha fatto l'agente.
claude mcp add aktar -- aktar mcp --root ~/Projects --log ~/aktar-mcp.log

aktar skill

Stampa una skill per agenti (SKILL.md) che insegna agli agenti a usare il comando aktar con --json: cosa eseguire, come leggere il risultato e di caricare solo ciò che hai chiesto di condividere. Per gli agenti che usano le skill ma non MCP.

Uso

aktar skill

Opzioni

Nessuna opzione.

Buono a sapersi

  • Salvala dove il tuo agente cerca le skill, ad esempio ~/.claude/skills/aktar/ per Claude Code.

Esempi

Installa la skill per Claude Code.
mkdir -p ~/.claude/skills/aktar
aktar skill > ~/.claude/skills/aktar/SKILL.md

Opzioni valide per ogni comando

FlagValoreDescrizione
-h, --helpMostra l'elenco dei comandi e delle opzioni.
-v, --versionMostra la versione di aktar.
--port<port>La porta dell'API locale di Aktar, solo per questo comando. Ha la precedenza su AKTAR_PORT e sulla porta salvata.

Output

Formati

-f sceglie cosa stampare per ogni caricamento. Senza, aktar stampa l'URL semplice, qualunque sia il formato che copia la barra dei menu di Aktar. Markdown e HTML incorporano le immagini e mettono un link a tutto il resto, come fa Aktar.

FormatoStampato per photo.jpg
-f urlhttps://files.example.com/2026/10/7f3c2a91.jpgIl link (predefinito).
-f markdown![](https://files.example.com/2026/10/7f3c2a91.jpg)Un'immagine Markdown, o un link Markdown per gli altri file.
-f html<img src="https://files.example.com/2026/10/7f3c2a91.jpg" alt="">Un tag <img>, o un link <a> per gli altri file.
-f custom![photo.jpg](https://files.example.com/2026/10/7f3c2a91.jpg)Il tuo modello dalle impostazioni di Aktar, con {url}, {filename} e le altre variabili compilate.

stdout e stderr

Lo standard output riceve solo i link, uno per riga, nell'ordine dei file (e i codici QR, con --qr). Tutto il resto va sullo standard error: avanzamento, errori e note come aktar: photo.jpg: already uploaded, reused the existing link. Così url=$(aktar upload file) e aktar upload *.png > links.txt ricevono sempre link puliti.

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

JSON

--json stampa un array con una voce per ogni file caricato, dopo che sono finiti tutti. I caricamenti non riusciti restano fuori (vengono segnalati su stderr), quindi controlla anche il codice di uscita.

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
  }
]
CampoSignificato
idL'ID del caricamento nella cronologia di Aktar. aktar qr lo accetta.
filenameIl nome con cui Aktar conosce il file: il suo nome originale o --name.
objectKeyDove si trova il file nel bucket.
urlIl link.
shortUrlIl link breve, o null se non c'è. formats lo usano già.
destinationIdL'ID della destinazione.
destinationNameIl nome della destinazione.
mimeTypeIl tipo del file, dopo un'eventuale conversione da parte di Aktar.
sizeDimensione in byte, così come è archiviato.
createdAtQuando è stato caricato (ISO 8601, UTC).
expiresAtQuando il bucket lo elimina, oppure null se viene conservato.
replacedAtQuando il file è stato sostituito l'ultima volta (ISO 8601, UTC). Assente finché non viene sostituito, e nelle versioni di Aktar precedenti a Mac 0.14.0 e Windows 0.7.0.
formatsIl link in tutti e quattro i formati: url, markdown, html e custom.
reusedtrue quando non è stato caricato nulla perché lo stesso file c'era già. Assente nelle versioni di Aktar precedenti a Mac 0.10.0 e Windows 0.3.0.
shortLinkErrorPerché Aktar non è riuscito a creare il link breve; url è allora il link originale. Assente se è andato tutto bene.

Codici di uscita

CodiceSignificato
0Tutto è andato a buon fine.
1Almeno un caricamento o una richiesta non è riuscita; gli altri sono andati comunque a buon fine. Anche gli errori di Aktar, come l'eliminazione automatica non configurata, finiscono qui.
2Argomenti non validi, un file che non esiste o un nome di destinazione che Aktar non ha. Non è stato caricato nulla.
3Accesso non effettuato, Aktar non è in esecuzione, la sua API locale è disattivata, il token è sbagliato o l'app sulla porta non è riuscita a dimostrare di essere Aktar (o è troppo vecchia per farlo).

Esempi pratici

Copia, adatta i nomi dei file, fatto. Ogni esempio usa solo quello che è documentato sopra.

Salvare il link in una variabile

Solo il link arriva sullo standard output, quindi la sostituzione di comando ottiene esattamente l'URL. || exit 1 interrompe lo script se il caricamento non è riuscito.

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

Caricare una build e pubblicare il link

Comprimi una build in zip, caricala su una destinazione chiamata Builds con l'hash breve del commit come nome e pubblica il link su qualsiasi webhook che accetti JSON (un canale di chat, un issue tracker, un tuo endpoint). set -e si ferma prima della pubblicazione se il caricamento non riesce.

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

Un target del Makefile

make share carica il report con la data di oggi come nome e salva il link in .last-link. In un Makefile, $$ passa un $ alla shell e la riga di comando inizia con un tab.

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

Caricare le immagini da Typora

In Typora, apri Settings > Image, scegli Custom Command come image uploader e inserisci il percorso completo di aktar (quello che stampa which aktar) seguito da upload. Typora passa i percorsi delle immagini e legge un link per riga.

/opt/homebrew/bin/aktar upload

Passo per passo, con l'impostazione When Insert…: Caricare le immagini di Typora su S3.

Caricare dal Finder o da Comandi rapidi

Su Mac, aggiungi un'azione Esegui script shell a un comando rapido, o a un'Azione rapida di Automator che riceve file nel Finder, e imposta il passaggio dell'input come argomenti. Comandi rapidi e Automator non caricano il PATH della tua shell, da qui la prima riga. Seleziona i file, eseguila e i link sono negli Appunti.

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

Carica file, non cartelle. Più file danno più link, uno per riga.

File temporanei

Per un log, una registrazione dello schermo o qualsiasi cosa che non debba restare, lascia che sia il bucket a eliminarla. Prima la destinazione deve avere le regole di eliminazione automatica di Aktar: configurale una volta da Elimina dopo nella barra dei menu di Aktar o nelle impostazioni della destinazione.

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

I file in scadenza finiscono sotto tmp/1d/, tmp/7d/ e così via nel bucket, e il bucket li elimina anche quando Aktar non è in esecuzione.

Aprire un link sul telefono

--qr stampa un codice QR sotto il link: inquadra il terminale con la fotocamera del telefono. Per mostrarlo di nuovo più tardi, passa l'ID di un caricamento ad aktar qr, qui l'ultimo caricamento che corrisponde a «demo».

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

Windows PowerShell

Lo stesso funziona in PowerShell. $LASTEXITCODE contiene il codice di uscita e ConvertFrom-Json legge --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 in Claude Desktop, Cursor o VS Code

Le app che accettano una configurazione JSON per i server MCP (Claude Desktop, Cursor, Windsurf e altre) hanno bisogno di questa voce. VS Code usa la stessa voce sotto servers in .vscode/mcp.json. Poi chiedi al tuo agente di caricare un file, trovare gli screenshot della settimana scorsa o creare un link temporaneo.

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

Se l'app non trova aktar, usa il suo percorso completo (which aktar), oppure npx con ["-y", "@getaktar/cli", "mcp", "--root", "/Users/you/Projects"] come argomenti. Dopo --root metti la cartella da cui il tuo agente può caricare (su Windows, ad esempio C:\\Users\\you\\Projects).

Cosa fa Aktar per te

La CLI si limita a passare i file; al resto pensa Aktar, con le impostazioni di ogni destinazione. Quindi tutto quello che hai configurato nell'app vale anche per aktar upload, senza opzioni aggiuntive, e il link che ottieni è quello del file così come è archiviato.

  • Modelli di percorso

    Il percorso dell'oggetto della destinazione dà il nome al file, con {year}, {uuid}, {filename} e gli altri. {md5} e {sha256} danno ai file un nome in base al contenuto.

  • Elaborazione immagini

    Se la destinazione converte le immagini in WebP o AVIF, le comprime o le ridimensiona, i caricamenti dalla CLI ricevono lo stesso trattamento e il link punta al file convertito.

  • Metadati delle foto

    Metadati immagine, tra le impostazioni di caricamento predefinite della destinazione, rimuove dalle foto la posizione, o tutti i metadati, prima che lascino il tuo computer.

  • Stesso file, stesso link

    Con Riutilizza i link per i file duplicati attivo, lo stesso contenuto nella stessa destinazione riceve il link esistente invece di un secondo caricamento. aktar lo segnala su stderr.

  • File grandi

    I file grandi vengono caricati in parti, senza il limite di 5 GB, ritentati dopo una connessione caduta e ripresi da dove si erano fermati. aktar invia il file ad Aktar in streaming, quindi non lo carica mai in memoria.

  • Link pubblici o temporanei

    Se il link è pubblico o temporaneo (prefirmato), e quindi funziona anche con un bucket privato, lo decide la destinazione, come nell'app.

Link per i duplicati, elaborazione delle immagini, {md5} e {sha256} e caricamenti in parti sono arrivati con Aktar per Mac 0.10.0 e Windows 0.3.0: novità della 0.10.0.

Risoluzione dei problemi

I messaggi di errore di aktar iniziano con aktar: e vanno su stderr. Il codice di uscita ti dice di che tipo di problema si tratta.

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

Apri Aktar e verifica che Consenti connessioni locali sia attivo in Impostazioni > Integrazioni. Se lì hai cambiato la porta, passala con --port o AKTAR_PORT, oppure esegui di nuovo aktar login --port. Codice di uscita 3.

Not connected to Aktar yet

Non c'è un token salvato né AKTAR_TOKEN. Esegui aktar login con il token da Impostazioni > Integrazioni di Aktar. Codice di uscita 3.

The token doesn't match Aktar's anymore

Il token è stato rigenerato in Aktar, oppure è stato digitato male. Esegui di nuovo aktar login con quello attuale. Se AKTAR_TOKEN è impostata, ha la precedenza sul token salvato, quindi aggiorna o rimuovi anche quella. Codice di uscita 3.

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

Qualcosa ha risposto sulla porta di Aktar ma non è riuscito a dimostrare di avere il tuo token, quindi il token non è stato inviato. Se Aktar è in esecuzione, probabilmente il suo token è cambiato: esegui di nuovo aktar login. Se Aktar non è in esecuzione, aprilo. Codice di uscita 3.

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

aktar 0.6.0 e successivi verificano l'app prima di inviare il token, e questo richiede Aktar per Mac 0.18.0 o Aktar per Windows 0.11.0 o successivo. Aggiorna Aktar (propone gli aggiornamenti da solo) e il comando torna a funzionare. Codice di uscita 3.

MCP: This server doesn't upload local files

L'agente ha avviato aktar mcp nella tua cartella Inizio o nella radice del disco, senza --root. Aggiungi al comando o alla configurazione del server --root con la cartella da cui possono provenire i file, ad esempio aktar mcp --root ~/Projects, e riavvia l'agente.

Auto-delete isn't set up for this destination

--expires richiede le regole di eliminazione automatica del bucket. Configurale una volta da Elimina dopo nella barra dei menu di Aktar o nelle impostazioni della destinazione, oppure carica senza --expires. Codice di uscita 1.

No destination named "…"

Il messaggio elenca i nomi che Aktar conosce. Controlla come l'hai scritto, metti tra virgolette i nomi con spazi (-d "Client work") oppure usa l'ID da aktar destinations. Codice di uscita 2.

Un caricamento grande richiede molto tempo

Dipende dalla velocità del provider di storage: aktar non ha limiti di tempo per i caricamenti e in un terminale mostra l'avanzamento su stderr. Tieni Aktar aperto finché non ha finito. Se la connessione cade o Aktar si chiude (Aktar closed the connection before the request finished), carica di nuovo lo stesso file: Aktar per Mac 0.10.0 e Windows 0.3.0 riprendono dall'ultima parte.

aktar non si avvia: SyntaxError o parseArgs

La tua versione di Node.js è precedente alla 18. Controlla con node --version e aggiornala, oppure installa aktar con Homebrew, che porta con sé il suo Node.js.

PowerShell dice che l'esecuzione di script è disabilitata

I criteri di esecuzione di PowerShell bloccano lo script che npm installa per aktar. Esegui invece aktar.cmd, oppure consenti gli script locali una volta con Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.