CLI
Installa linkdash-cli da npm, poi esegui il comando `linkdash`. I comandi andati a buon fine stampano JSON su stdout. Aiuto ed errori sono testo semplice su stderr.
npm i -g linkdash-cli
# or: pnpm add -g linkdash-cli / bun add -g linkdash-cli / npx linkdash-cli@latest
Il pacchetto npm è linkdash-cli. Il comando è linkdash.
Equivalente HTTP: API HTTP. MCP: MCP. Skill per agenti: Skill per agenti. Prezzi: Prezzi. Markdown semplice: cli.md.
Non esiste un flag --json. In caso di errore il codice di uscita è 1.
Autenticazione
linkdash auth create
linkdash auth login
linkdash auth whoami
linkdash auth logout
Non hai ancora un account? auth create apre https://linkdash.dev/sign-up, poi torna su https://linkdash.dev/device con il codice della CLI, così puoi approvare. Hai già un account? auth login apre /device. In modalità headless: imposta LINKDASH_TOKEN con un token di sessione ottenuto da auth create o auth login. Non inventare token.
File di sessione: ~/.config/linkdash/config.json (modalità 0600).
La CLI non può cambiare email, password o fatturazione. Indirizza l’utente alla dashboard. Chiavi API (HTTP e MCP): Chiavi API.
Comandi
linkdash <command> [options]
| Comando | Cosa fa |
|---|---|
auth create |
Registrazione dal browser, poi approvazione del dispositivo |
auth login |
Login dal browser tramite dispositivo |
auth logout |
Dimentica la sessione salvata |
auth whoami |
JSON dell’account con cui hai effettuato l’accesso |
links list |
Elenca link e cartelle, una pagina alla volta (--limit, --cursor) |
links get <id> |
Un singolo link |
links create --url <url> |
Link breve da un URL |
links create --file <path> |
Carica un file e ottieni un link |
links create --text <text> |
Salva uno snippet |
links create --folder <name> |
Crea una cartella |
links create --variant <name> … |
Link con più varianti (split / targeting) |
links update <id> |
Cambia destinazione, file, password, scadenza, dominio, stato, sticky o parametri inoltrati |
links move <id> --in <folder-id> |
Metti un link o una cartella dentro una cartella (--root per il livello principale) |
links copy <id> |
Crea una copia con un nuovo slug, nella stessa cartella |
links delete <id> |
Elimina un link (gli elementi di una cartella salgono di un livello; --with-contents li elimina) |
links share <id> --email <email> |
Condividi con altre persone via email (ripeti --email; --role editor permette loro di modificarlo; ogni nuova persona riceve un’email di invito) |
links unshare <id> --email <email> |
Rimuovi l’accesso a qualcuno |
links shares [id] |
Chi può aprirlo oltre a te, anche tramite una cartella che lo contiene. Senza id: tutto ciò a cui hai invitato altre persone, una pagina alla volta (--limit, --cursor) |
links shared |
Ciò che altre persone hanno condiviso con te, una pagina alla volta (--limit, --cursor) |
links leave <_id | share URL> |
Rinuncia a qualcosa che è stato condiviso con te |
links role <id> --email <e> --role viewer|editor |
Rendi viewer o editor una persona che hai invitato |
links unlock <_id | share URL> |
Inserisci la password di un elemento condiviso per vederne e modificarne la destinazione per 30 minuti |
links activity <id> |
Chi ha modificato un elemento e come |
links reset-link <id> |
Nuovo URL di condivisione; il vecchio URL linkdash.dev/s/ smette di funzionare |
links stats <id> |
Totali di visite, download e riproduzioni, anche per variante, più i crawler |
links export |
Stampa tutti i link in CSV (una riga per variante) |
links import <file> |
Importa righe di URL e testo da un CSV |
links variants list <id> |
Varianti di un link |
links variants add <id> --name <n> |
Aggiungi una variante |
links variants update <id> <name> |
Modifica una variante |
links variants remove <id> <name> |
Rimuovi una variante |
webhooks list |
Elenca gli endpoint webhook (secret mascherato) |
webhooks get <id> |
Mostra l’URL di un webhook (secret mascherato) |
webhooks create --url <https> |
Aggiungi un endpoint HTTPS (il secret viene mostrato una sola volta) |
webhooks rotate <id> |
Genera un nuovo secret di firma |
webhooks delete <id> |
Rimuovi un webhook |
domains list |
Elenca gli hostname personalizzati |
domains add <host> |
Aggiungi un hostname (1 nel piano Free) |
domains connect <host> |
URL di applicazione Domain Connect, oppure null |
domains verify <host> |
Controlla il DNS con Unkey |
domains remove <host> |
Rimuovi un hostname |
-h, --help |
Aiuto (testo semplice) |
-v, --version |
Versione |
Se lo stesso slug esiste su due domini del proprietario, passa --domain.
Flag di creazione e aggiornamento
Lo slug è l’id del link, e anche il suo percorso pubblico quando il link è pubblico. Il nome è visibile solo a te. I nuovi link sono ad accesso ristretto (vedi Accesso e condivisione). Create accetta esattamente uno tra --url, --file o --text (che diventa la variante main), blocchi --variant (vedi Varianti) oppure --folder <name> (vedi Cartelle).
| Flag | Note |
|---|---|
--url <url> |
URL di destinazione |
--file <path> |
File da caricare (in creazione, oppure per sostituirne i byte in aggiornamento) |
--text <text> |
Snippet |
--access <restricted|link|public> |
Chi può aprirlo. Predefinito restricted. Vedi Accesso e condivisione |
--reset-share-link |
Genera un nuovo URL di condivisione (solo update) |
--slug <id> |
Percorso pubblico: a-z0-9 e trattini interni, 1–64 |
--name <label> |
Etichetta privata |
--tag <tag> |
Ripetibile. In minuscolo, senza virgole. Max 20 |
--starts <when> |
Va online dopo 7d, 24h, 30m o una data ISO |
--password <secret> |
Richiede questa password per aprirlo |
--expires <when> |
Smette di essere servito dopo 7d, 24h, 30m o una data ISO |
--max-openings <n> |
Va in pausa dopo questo numero di aperture. Omettilo per aperture illimitate |
--domain <host> |
Servilo su questo host invece che su lida.sh |
--in <folder-id> |
Crea dentro questa cartella (solo create; --in-domain <host> se lo slug della cartella si ripete) |
--status <active|paused> |
Metti in pausa o riattiva (solo update) |
--sticky / --no-sticky |
Chi torna mantiene la stessa variante (sticky di default) |
--restart-split |
Rimescola le assegnazioni sticky (solo update) |
--forward-params / --no-forward-params |
Aggiunge la query string del visitatore alle varianti URL (disattivato di default). Vedi Inoltrare i parametri di query |
--variant <name> |
Avvia un blocco di variante (solo create). Vedi Varianti |
--weight <n> --when <key=v1,v2> |
Per variante. Vedi Varianti e Regole sui parametri di query |
--preview-name <text> |
Nome pubblico nell’anteprima (unfurl) |
--preview-description <text> |
Descrizione pubblica nell’anteprima |
--preview-image <path> |
Immagine pubblica nell’anteprima |
--utm-source --utm-medium --utm-campaign --utm-term --utm-content |
Solo link URL |
--clear-password --clear-expires --clear-starts --clear-tags --clear-preview --clear-name --clear-max-openings |
Solo update |
--status accetta solo active o paused. Lo stato scaduto deriva da --expires. Lo stato programmato deriva da --starts. Fino all’inizio, la risoluzione pubblica restituisce not-found. Quando viene raggiunto --max-openings il link va in pausa; aumenta il numero, oppure usa --clear-max-openings, per servirlo di nuovo. Le aperture già usate restano conteggiate finché non modifichi o rimuovi il limite.
Gli slug di lida.sh sono condivisi tra tutti. Se una parola è già presa, aggiungi un dominio personalizzato e riprova con --domain. Un link su un dominio brandizzato non viene pubblicato anche su lida.sh.
Flag di elenco
Stampa una pagina, {items, cursor}: --limit va da 1 a 100 (predefinito 50); passa --cursor con il cursor della pagina precedente finché non diventa null. Una pagina può contenere meno elementi di --limit quando un filtro ne scarta alcuni. --q cerca parole intere, con l’ultima trattata come prefisso (laun trova example.com/launch), ordinate per rilevanza; --in elenca una cartella, con le cartelle per prime; altrimenti l’ordine è dal più recente.
| Flag | Note |
|---|---|
--limit <n> |
Elementi per pagina, 1-100 (predefinito 50) |
--cursor <c> |
Il cursor della pagina precedente |
--q <text> |
Cerca parole in nome, slug, nomi e destinazioni delle varianti, nomi dei file, testo degli snippet e tag |
--tag <tag> |
Filtra per tag |
--kind <url|file|text|folder|group> |
Filtra per tipo (group = più varianti) |
--status <status> |
active, paused, expired, scheduled o mixed |
--in <folder-id|root> |
Solo ciò che si trova direttamente in questa cartella, o al livello principale. Senza questo flag viene elencato tutto |
Varianti
Ogni link è un contenitore di una o più varianti. Una variante è il contenuto (URL, file o testo) più le sue regole di accesso (--password, --starts, --expires, --max-openings), un --weight e condizioni opzionali sul visitatore (--when). Senza --variant un link ha una sola variante chiamata main, e ogni comando qui sopra agisce su di essa. Ogni visitatore riceve una variante: le varianti il cui --when corrisponde formano il pool (se nessuna corrisponde, il pool è formato dalle varianti senza condizioni), poi ne viene scelta una in base al peso. Con l’assegnazione sticky (predefinita) un visitatore che torna mantiene la stessa variante. Le regole di accesso del link hanno la precedenza su quelle delle varianti. Nomi delle varianti: lettere minuscole, cifre, trattini interni, 1–40 caratteri, univoci per link. Max 20 varianti.
Il kind del link è il tipo della variante se ce n’è una sola, e group se ce ne sono diverse. Lo status del link è quello delle regole di accesso del link quando impostate (paused, scheduled, expired), altrimenti lo stato comune a tutte le varianti, altrimenti mixed. variantStatuses conta {active, paused, expired, scheduled}.
Creare con blocchi di variante
linkdash links create --slug promo --variant a --url https://example.com/a --variant b --url https://example.com/b --weight 3
linkdash links create --slug hi --variant de --url https://example.de --when country=DE,AT --variant rest --url https://example.com
--variant <name> avvia un blocco di variante. I flag che lo seguono appartengono a quella variante fino al --variant successivo: --url|--file|--text, --password, --starts, --expires, --max-openings, --weight <n>, --when <key=v1,v2> (ripetibile), --utm-*. I flag del link (--slug --name --tag --domain --preview-* --password --starts --expires --max-openings --sticky --no-sticky --forward-params) vanno prima del primo --variant.
Sottocomandi delle varianti
linkdash links variants list promo
linkdash links variants add promo --name mobile --url https://m.example.com --when device=mobile
linkdash links variants update promo mobile --when country=DE,AT --when device=mobile --weight 2
linkdash links variants update promo b --status paused
linkdash links variants remove promo b
variants add <id> --name <n> accetta uno tra --url, --file, --text, più i flag delle regole di accesso, --weight, --when, --utm-*. variants update <id> <name> accetta --name <new>, il contenuto, i flag delle regole di accesso, --status active|paused, --weight, --when, --clear-when, --clear-password, --clear-starts, --clear-expires, --clear-max-openings. Un link deve avere sempre almeno una variante.
Chiavi di --when
| Chiave | Campo JSON | Valori |
|---|---|---|
country |
countries |
Codici ISO-2 (DE, AT) |
device |
devices |
mobile tablet desktop |
os |
os |
windows macos android ios linux other |
browser |
browsers |
edge chrome firefox safari other |
language |
languages |
corrispondenza per prefisso (de, en-us) |
referrer |
referrerHosts |
suffisso dell’host (twitter.com) |
Ogni chiave impostata deve corrispondere. --when country=DE,AT --when device=mobile equivale a { "countries": ["DE","AT"], "devices": ["mobile"] }.
Regole sui parametri di query
--when accetta anche regole param: sulla query string del visitatore (lida.sh/promo?src=newsletter). Le chiavi sono case-sensitive, i valori vengono confrontati in modo esatto, max 10 regole per variante. Le virgole fanno da separatore in --when, quindi il valore di un parametro non può contenere una virgola; usa | per gli elenchi.
| Sintassi | op JSON |
Corrisponde quando |
|---|---|---|
param:KEY=VALUE |
equals |
il valore è esattamente VALUE |
param:KEY!=VALUE |
notEquals |
il valore è diverso, o la chiave è assente |
param:KEY~=VALUE |
includes |
il valore contiene VALUE |
param:KEY^=VALUE |
startsWith |
il valore inizia con VALUE |
param:KEY$=VALUE |
endsWith |
il valore termina con VALUE |
param:KEY=v1|v2 |
in |
il valore è uno di quelli dell’elenco |
param:KEY? or param:KEY |
exists |
la chiave è presente |
param:!KEY |
missing |
la chiave è assente |
linkdash links variants add promo --name news --url https://example.com/news --when param:src=newsletter
linkdash links variants add promo --name pro --url https://example.com/pro --when "param:plan~=pro"
linkdash links variants add promo --name ref --url https://example.com/ref --when "param:ref?"
Forma JSON: "when": { "params": [{ "key": "src", "op": "equals", "value": "newsletter" }] } (value viene omesso per exists / missing). I valori dei parametri vengono confrontati al momento dell’apertura e non vengono mai salvati nelle analytics.
Inoltrare i parametri di query
--forward-params / --no-forward-params su links create e links update (a livello di link, disattivato di default) aggiunge l’intera query string del visitatore alle varianti URL: lida.sh/promo?src=nl apre https://example.com/?src=nl. I valori del visitatore sovrascrivono quelli salvati, --utm-* compresi. Le varianti file e testo lo ignorano. È una funzione di routing, non di controllo degli accessi: chiunque può aggiungere parametri. I valori dei parametri non vengono salvati nelle analytics. links get lo mostra come forwardParams.
Sticky e riavvio dello split
links update <id> --sticky / --no-sticky imposta se un visitatore che torna mantiene la stessa variante. links update <id> --restart-split rimescola le assegnazioni sticky. I flag di contenuto su links update funzionano solo per i link con una sola variante; negli altri casi usa links variants update <id> <name>.
Cartelle
Una cartella è un link che elenca gli elementi che ci metti dentro. Vedi Cartelle per capire come funzionano la pagina pubblica e l’accesso.
linkdash links create --folder "Q4 launch" --slug q4
linkdash links create --file ./deck.pdf --in q4
linkdash links move k3m9xq --in q4
linkdash links move k3m9xq --root
linkdash links list --in q4
linkdash links copy k3m9xq
linkdash links delete q4 --with-contents
--folder <name> imposta il nome della cartella (non --name) e accetta --slug, --domain, --password, --starts, --expires, --max-openings, --tag, --preview-* e --in. Non può essere combinato con --url, --file, --text o --variant. links move stampa {id, folder}. links copy mantiene il livello di accesso ma ottiene un nuovo URL di condivisione; le persone non vengono copiate. links delete su una cartella sposta i suoi elementi di un livello più in alto; --with-contents elimina anche quelli. Le righe di list, get e create includono folder (lo slug della cartella che contiene l’elemento, oppure null); le righe delle cartelle includono anche items.
Accesso e condivisione
I nuovi link e le nuove cartelle sono restricted: il loro url è https://linkdash.dev/s/<token>, che possono aprire solo tu e le persone con cui lo condividi, dopo aver effettuato l’accesso. --access link rende quell’URL apribile da chiunque lo abbia. --access public serve il link al suo URL breve (lida.sh/<slug> o il tuo dominio personalizzato). Usa --access public per i link che pubblichi apertamente. Lo slug resta l’id per tutti i comandi, e il suo URL breve resta riservato finché il link non è pubblico. Vedi Condivisione e accesso per il modello completo.
linkdash links create --url https://example.com/launch --access public
linkdash links share q4 --email anna@example.com --email ben@example.com
linkdash links shares q4
linkdash links unshare q4 --email ben@example.com
linkdash links shared
linkdash links leave https://linkdash.dev/s/<token>
linkdash links share q4 --email cara@example.com --role editor
linkdash links role q4 --email cara@example.com --role viewer
linkdash links unlock https://linkdash.dev/s/<token>
linkdash links activity q4
linkdash links shares
linkdash links update q4 --access link
linkdash links reset-link q4
| Comando | Stampa |
|---|---|
links share <id> --email <e> [--email <e> …] |
{id, url, access, invited, alreadyShared} |
links unshare <id> --email <e> |
{id, email, removed: true} |
links shares <id> |
{id, access, url, people: [{email, role: "viewer", accepted, invitedAt, viaFolder?}]} |
links shares (senza id) |
{items: [{id, name?, kind, access, url, people: [{email, accepted, invitedAt}]}], cursor}, dal condiviso più di recente |
links shared |
{items: [{_id, _creationTime, kind, title?, status, hasPassword, access, url, itemCount?, sharedBy?, sharedAt}], cursor}, dal più recente |
links leave <_id | share URL> |
{_id, left: true} |
links role <id> --email <e> --role <r> |
{id, email, role} |
links unlock <_id | share URL> |
{_id, variant, unlocked: true, minutes: 30, kind, destinationUrl? | textContent? | fileName?} |
links activity <id> |
{items: [{_id, _creationTime, action, detail?, actor}], cursor} |
links reset-link <id> (o links update <id> --reset-share-link) |
{id, access, url} |
--role editor rende qualcuno editor: può modificare l’elemento e vederne le statistiche, ma non può toccare password, slug, dominio, accesso o condivisione, né eliminare, spostare o copiare l’elemento; inoltre una destinazione protetta da password richiede prima links unlock (30 minuti). Gli editor usano l’_id o l’URL di condivisione restituiti da links shared. Tutti i comandi accettano --domain <host> quando lo slug si ripete. Il campo url nell’output di create, get, list, update, copy e share è l’URL di condivisione, a meno che il link non sia pubblico: in quel caso è l’URL breve; le righe includono access. Fino a 200 persone per elemento, 50 email per chiamata, 100 email di invito per account al giorno. Le due liste stampano una pagina: --limit va da 1 a 100 (predefinito 50); passa --cursor della pagina precedente finché cursor non diventa null. links leave accetta l’_id o l’url restituiti da links shared; l’accesso tramite una cartella condivisa più in alto rimane. Condivisione, revoca della condivisione, modifica dell’accesso e reset contano ciascuno come un evento; abbandonare un elemento no.
Statistiche
linkdash links stats <id> --last 24h
--last è una durata (24h, 7d). Predefinito 24h. Il JSON include visits, downloads, plays, visitsInLast, countries, referrers, variants (totali per variante), visitors (ognuno con la sua variant) e crawlers ([{crawler, company, category, hits, lastSeen}]: bot e anteprime di link che hanno recuperato il link, mai conteggiati come visite).
CSV
Colonne: slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access. Una riga per variante. kind, status, url, text, fileName, weight e when (stringa JSON) sono per variante; le altre sono per link e si ripetono. folder è lo slug della cartella in cui si trova il link. access è restricted, link o public. Niente password, token di condivisione o persone.
linkdash links export > links.csv
linkdash links import links.csv
L’import raggruppa le righe per slug + dominio. La prima riga crea il link con la sua variante; le righe successive aggiungono varianti. Per un link esistente, la prima riga aggiorna i campi del link, poi ogni riga aggiorna la variante con quel nome se esiste, altrimenti la aggiunge. Le righe di tipo file senza byte vengono saltate con un errore per riga. Le righe con kind = folder (con un name) creano cartelle; la colonna folder sposta ogni link nella sua cartella dopo che tutte le righe sono state create. Un access vuoto rende ad accesso ristretto i nuovi link e lascia invariati quelli esistenti.
Esempi
linkdash links create --url https://example.com/q4/deck.pdf --slug deck --name "Q4 deck"
linkdash links create --file ./deck.pdf --expires 7d --starts 1d
linkdash links create --url https://example.com --max-openings 1
linkdash links update k3m9xq --max-openings 5
linkdash links update k3m9xq --clear-max-openings
linkdash links create --text "release checklist" --tag launch --tag q4
linkdash links list --q deck --tag launch --kind file --status paused
linkdash links get welcome --domain go.example.com
linkdash links update deck --file ./new.pdf
linkdash links update k3m9xq --status paused
linkdash links create --slug promo --variant a --url https://example.com/a --variant b --url https://example.com/b --weight 3
linkdash links variants add promo --name mobile --url https://m.example.com --when device=mobile
linkdash links update promo --no-sticky --restart-split
linkdash links create --folder "Q4 launch" --slug q4
linkdash links move k3m9xq --in q4
linkdash links create --url https://example.com/launch --access public
linkdash links share q4 --email anna@example.com
Vedi anche cartelle, condivisione e accesso, webhook e domini personalizzati.

