---
title: CLI
description: >-
  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.
sidebar:
  label: CLI
  order: 3
---
```bash
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](/it/api). MCP: [MCP](/it/mcp). Skill per agenti: [Skill per agenti](/it/skill). Prezzi: [Prezzi](/it/pricing). Markdown semplice: [cli.md](https://linkdash.dev/cli.md).

Non esiste un flag `--json`. In caso di errore il codice di uscita è 1.

## Autenticazione

```bash
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](https://linkdash.dev/dashboard/billing). Chiavi API (HTTP e MCP): [Chiavi API](https://linkdash.dev/dashboard/keys).

## 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](/it/folders) |
| `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](/it/sharing) 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](#access-and-sharing)). Create accetta **esattamente uno** tra `--url`, `--file` o `--text` (che diventa la variante `main`), blocchi `--variant` (vedi [Varianti](#variants)) oppure `--folder <name>` (vedi [Cartelle](#folders)).

| 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](#access-and-sharing) |
| `--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](#forward-query-parameters) |
| `--variant <name>` | Avvia un blocco di variante (solo create). Vedi [Varianti](#variants) |
| `--weight <n>` `--when <key=v1,v2>` | Per variante. Vedi [Varianti](#variants) e [Regole sui parametri di query](#query-parameter-rules) |
| `--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](/it/domains) 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

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

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

```bash
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](/it/folders) per capire come funzionano la pagina pubblica e l'accesso.

```bash
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](/it/sharing) per il modello completo.

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

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

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

```bash
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](/it/folders), [condivisione e accesso](/it/sharing), [webhook](/it/webhooks) e [domini personalizzati](/it/domains).
