Vai al contenuto
Tutti gli articoli

climcpapi

Un URL shortener da riga di comando per sviluppatori e agenti IA

Accorcia URL dal terminale con la CLI di Linkdash. Condividi file e snippet, fai A/B test, targeting dei visitatori e gestisci i link con agenti IA via MCP.

Igor Kirnosov10 min di lettura

Un terminale che crea un link breve Linkdash con il comando linkdash links create

Linkdash è un URL shortener che gestisci dal terminale. Un solo comando trasforma un URL, un file o uno snippet di testo in un link breve tracciato su lida.sh e stampa il risultato in JSON, pronto da passare in pipe a qualsiasi cosa. Le stesse operazioni sono disponibili tramite un’API HTTP e come server MCP, così un agente IA può creare, aggiornare e misurare i link con gli stessi identici strumenti che usi tu.

Questa guida copre tutta la CLI: installazione, il primo link breve, condivisione di file, protezione dei link, A/B test, instradamento dei visitatori per paese o dispositivo e lettura delle statistiche senza aprire un browser.

La dashboard di Linkdash con l’elenco dei link brevi, con tipo, slug, destinazione e stato

Installa la CLI di Linkdash

La CLI è un pacchetto npm e richiede Node.js 20 o superiore.

npm i -g linkdash-cli

Funziona allo stesso modo con pnpm add -g linkdash-cli o bun add -g linkdash-cli. Il comando installato è linkdash.

Poi crea un account e collega la CLI, in un solo passaggio:

linkdash auth create

Si apre la pagina di registrazione nel browser. Una volta creato l’account, approvi il codice mostrato nel terminale e la CLI ha effettuato l’accesso. Se hai già un account, usa invece linkdash auth login. linkdash auth whoami conferma quale account stai usando, e il riferimento della CLI elenca ogni comando e flag.

La sessione viene salvata in ~/.config/linkdash/config.json con permessi riservati al proprietario. Per la CI o altri ambienti headless, imposta LINKDASH_TOKEN con il token di sessione preso da quel file su una macchina in cui hai effettuato l’accesso, e trattalo come qualsiasi altro secret.

Accorcia un URL dalla riga di comando

linkdash links create --url https://example.com/pricing --slug pricing
{
  "id": "pricing",
  "url": "https://lida.sh/pricing",
  "kind": "url",
  "variants": [
    { "name": "main", "kind": "url" }
  ]
}

L’interfaccia è tutta qui: i comandi riusciti stampano JSON su stdout, gli errori stampano testo semplice su stderr con codice di uscita 1. Non c’è un flag --json, perché il JSON è l’unico output. Questo rende la CLI facile da usare negli script. Per copiare un nuovo link breve direttamente negli appunti su macOS:

linkdash links create --url https://example.com/pricing | jq -r .url | pbcopy

Alcuni flag che userai di continuo:

  • --slug imposta il percorso pubblico. Gli slug usano lettere minuscole, cifre e trattini interni, fino a 64 caratteri. Se lo ometti, Linkdash ne genera uno.
  • --name è un’etichetta privata che vedi solo tu, comoda per ritrovare i link in seguito.
  • --tag si può ripetere, quindi --tag launch --tag q4 assegna due tag a un link.
  • --utm-source, --utm-medium, --utm-campaign, --utm-term e --utm-content aggiungono i parametri di campagna alla destinazione.

Elenca e cerca ciò che hai creato con linkdash links list --q pricing --tag launch.

Condividi un file o uno snippet di testo

I link brevi non servono solo per gli URL. Lo stesso comando carica un file o salva uno snippet:

linkdash links create --file ./board-deck.pdf --slug board-deck --expires 7d
linkdash links create --text "Release checklist: tag, build, smoke test, announce" --tag launch

Un link a un file offre ai visitatori un download, con anteprima per immagini e video. Un link di testo mostra lo snippet in una pagina con un pulsante per copiarlo. Entrambi sono tracciati come qualsiasi altro link, quindi puoi vedere chi ha aperto la tua presentazione e quando. Per sostituire il file dietro un link esistente senza cambiare l’URL:

linkdash links update board-deck --file ./board-deck-v2.pdf

Ogni link può avere le proprie regole di accesso:

linkdash links create --url https://example.com/decks/q4-2026 \
  --slug q4-deck \
  --password "$DECK_PASSWORD" \
  --expires 14d \
  --max-openings 50
  • --password chiede ai visitatori una password prima di aprire il link.
  • --starts ed --expires accettano una durata come 30m, 24h o 7d, oppure una data ISO. Prima dell’orario di inizio il link non si risolve affatto.
  • --max-openings mette in pausa il link dopo quel numero di aperture, utile per i download una tantum.

Puoi mettere in pausa e riattivare un link in qualsiasi momento con linkdash links update q4-deck --status paused e --status active.

In Linkdash ogni link è un contenitore di una o più varianti. Una variante è una destinazione (un URL, un file o un testo) con un proprio peso e proprie regole. Un link normale ha una sola variante chiamata main. Aggiungine altre e il link breve ripartisce il traffico tra di esse:

linkdash links create --slug launch \
  --variant control --url https://example.com/pricing \
  --variant annual-first --url "https://example.com/pricing?view=annual"

I flag dopo ogni --variant appartengono a quella variante fino alla successiva. Il traffico viene ripartito in base al peso, che di default è 1, quindi l’esempio qui sopra è un test 50/50. Assegna a una variante --weight 3 per mandarle il triplo del traffico.

L’assegnazione è persistente di default: un visitatore di ritorno continua a ricevere la stessa variante, ed è ciò che serve per un test corretto. Quando cambi l’esperimento, linkdash links update launch --restart-split rimescola tutti una volta.

Un link Linkdash con due varianti, control e annual-first, che ripartisce il traffico tra due pagine dei prezzi

Le statistiche arrivano per variante, così puoi confrontarle direttamente:

linkdash links stats launch --last 7d

L’array variants nell’output riporta visits, visitors, downloads e plays per ogni variante. Altro sulle statistiche più sotto.

Instrada i visitatori per paese, dispositivo o parametro di query

Le varianti possono avere anche delle condizioni. Aggiungi --when a una variante e solo i visitatori corrispondenti potranno riceverla. Così un link breve diventa un router. Per esempio, un link che manda gli smartphone allo store giusto:

linkdash links create --slug get-app \
  --variant ios \
    --url https://apps.apple.com/app/example/id000000000 \
    --when os=ios \
  --variant android \
    --url "https://play.google.com/store/apps/details?id=com.example" \
    --when os=android \
  --variant web \
    --url https://example.com/app

Quando un visitatore apre il link, le varianti con condizioni soddisfatte formano il gruppo di candidate. Se nessuna corrisponde, si usano le varianti senza condizioni, quindi web qui sopra raccoglie chiunque non sia su iOS o Android.

Un link Linkdash che manda i visitatori all’App Store su iOS, a Google Play su Android e a una pagina web per tutti gli altri

Puoi filtrare per:

Chiave Corrisponde a Esempio
country Codici paese ISO --when country=DE,AT,CH
device mobile, tablet, desktop --when device=mobile
os windows, macos, android, ios, linux, other --when os=ios
browser edge, chrome, firefox, safari, other --when browser=safari
language Tag di lingua, per prefisso --when language=de
referrer L’host di provenienza --when referrer=twitter.com

Ripeti --when per richiedere più condizioni insieme. --when country=DE,AT --when device=mobile corrisponde ai visitatori da mobile in Germania o Austria.

Le varianti possono anche basarsi sulla query string del visitatore, così un solo link può comportarsi in modo diverso a seconda di dove l’hai condiviso. lida.sh/launch?src=newsletter può mandare chi legge la newsletter in un posto speciale:

linkdash links variants add launch --name newsletter \
  --url https://example.com/pricing/newsletter \
  --when param:src=newsletter

Le regole sui parametri supportano uguale (=), diverso (!=), contiene (~=), inizia con (^=), finisce con ($=), uno tra (=a|b), presente (param:ref?) e assente (param:!ref). Se invece vuoi passare i parametri del visitatore alla destinazione, crea il link con --forward-params.

La dashboard ha gli stessi controlli, con un selettore di paesi che cerca per nome, così non devi ricordarti che la Slovenia è SI:

Selezione dei paesi di destinazione per una variante nella dashboard di Linkdash, con Germania e Austria selezionate

Leggi le statistiche dei clic dal terminale

linkdash links stats launch --last 7d

L’output include il totale di visits, downloads e plays, il numero di visite nella finestra richiesta (visitsInLast), i countries e i referrers da cui sono arrivate, un dettaglio per variants e un elenco visitors con ora, paese, dispositivo, browser e referrer di ogni visita recente. --last accetta una durata come 24h o 30d e di default vale 24h.

Linkdash non salva gli indirizzi IP dei visitatori. L’indirizzo serve a ricavare il paese del visitatore e a generare un identificatore anonimo che cambia ogni giorno, poi viene scartato.

Per reagire ai clic in tempo reale, registra un webhook. Linkdash invia eventi firmati link.visit, link.download e link.play a qualsiasi endpoint HTTPS:

linkdash webhooks create --url https://example.com/hooks

Il secret di firma viene stampato una sola volta, quindi salvalo subito. Consulta la documentazione sui webhook per verificare le firme.

Tutto quanto sopra è disponibile anche per gli agenti IA. Linkdash gestisce un server MCP remoto su https://api.linkdash.dev/mcp, e i suoi strumenti rispecchiano la CLI: links_create, links_update, links_stats, variants_add, domains_add e gli altri, con lo stesso JSON in risposta.

Crea una chiave API nella dashboard in Chiavi API, poi collega il tuo agente. In Claude Code:

claude mcp add --transport http linkdash https://api.linkdash.dev/mcp \
  --header "Authorization: Bearer $LINKDASH_API_KEY"

In Cursor, aggiungilo a .cursor/mcp.json:

{
  "mcpServers": {
    "linkdash": {
      "url": "https://api.linkdash.dev/mcp",
      "headers": { "Authorization": "Bearer ${env:LINKDASH_API_KEY}" }
    }
  }
}

In Codex, che legge la chiave dalla variabile d’ambiente che indichi:

codex mcp add linkdash --url https://api.linkdash.dev/mcp \
  --bearer-token-env-var LINKDASH_API_KEY

Da quel momento puoi chiedere i link in linguaggio naturale, per esempio «accorcia https://example.com/pricing come pricing e aggiungi il tag launch» oppure «quale variante di launch ha avuto più visitatori questa settimana?», e l’agente chiama lo strumento giusto. La documentazione MCP copre anche OpenCode.

Se il tuo agente lavora già in un terminale, può usare direttamente la CLI. Installa la skill per agenti di Linkdash, così conosce comandi e flag:

npx skills add https://linkdash.dev/skills/linkdash/SKILL.md

Usa l’API HTTP

Per il tuo codice, le stesse operazioni sono una semplice API REST su https://api.linkdash.dev/v1, autenticata con la stessa chiave API:

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer $LINKDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/pricing", "slug": "pricing" }'

La risposta ha la stessa forma dell’output della CLI. Il riferimento dell’API copre ogni endpoint, compresi il caricamento di file e le varianti.

Usa il tuo dominio

Di default i link brevi stanno su lida.sh. Per servirli dal tuo dominio, aggiungilo e punta il DNS verso Linkdash:

linkdash domains add go.example.com
linkdash domains verify go.example.com

Poi crea i link su quel dominio con --domain go.example.com. Ogni dominio personalizzato ha il proprio insieme di slug, quindi go.example.com/launch non entra in conflitto con il launch di nessun altro. La guida ai domini copre la configurazione DNS, compresa la configurazione in un clic per i provider che la supportano.

Prezzi

Il piano Free non richiede carta di credito e include 5.000 eventi al mese, 1 GB di spazio per i file, un mese di cronologia delle statistiche e un dominio personalizzato. Un evento è una visita, un download o una riproduzione su uno dei tuoi link, oppure una scrittura come la creazione o la modifica di un link. Le letture, come elencare i link o recuperare le statistiche, sono gratuite.

I piani a pagamento alzano questi limiti: Professional costa 18 $ al mese e Growth 48 $ al mese. Consulta i prezzi per il confronto completo.

Domande frequenti

Esiste un URL shortener gratuito con una CLI?

Sì. La CLI di Linkdash funziona con il piano Free, che include 5.000 eventi al mese senza carta di credito.

Posso usare la CLI di Linkdash nella CI?

Sì. Imposta LINKDASH_TOKEN con un token di sessione e la CLI funziona senza browser. Dato che ogni comando stampa JSON, puoi creare e aggiornare link da GitHub Actions o da qualsiasi altra pipeline e leggere i risultati con jq.

Sì, in tre modi: tramite il server MCP su https://api.linkdash.dev/mcp, tramite la CLI con la skill per agenti di Linkdash installata, oppure tramite l’API HTTP. Tutti e tre offrono le stesse operazioni e restituiscono lo stesso JSON.

Linkdash salva gli indirizzi IP dei visitatori?

No. Linkdash usa l’indirizzo per ricavare il paese del visitatore e creare un identificatore anonimo giornaliero, poi lo scarta. I proprietari dei link non vedono mai gli indirizzi IP.

Sì. Assegna più varianti a un link e aggiungi a ciascuna condizioni come paese, dispositivo, sistema operativo, lingua, referrer o parametro di query. Senza condizioni, le varianti ripartiscono il traffico in base al peso: è così che si fa un A/B test.


Vuoi provarlo? Installa la CLI, esegui linkdash auth create e accorcia il tuo primo link in meno di un minuto. La guida rapida ha tutti i passaggi.