CLI
Installez linkdash-cli depuis npm, puis exécutez la commande `linkdash`. Les commandes réussies affichent du JSON sur stdout. L'aide et les erreurs s'affichent en texte brut sur stderr.
npm i -g linkdash-cli
# or: pnpm add -g linkdash-cli / bun add -g linkdash-cli / npx linkdash-cli@latest
Le paquet npm est linkdash-cli. La commande est linkdash.
Équivalent HTTP : API HTTP. MCP : MCP. Skill d’agent : Skill d’agent. Tarifs : Tarifs. Markdown brut : cli.md.
Il n’y a pas d’option --json. La CLI renvoie le code de sortie 1 en cas d’erreur.
Authentification
linkdash auth create
linkdash auth login
linkdash auth whoami
linkdash auth logout
Pas encore de compte ? auth create ouvre https://linkdash.dev/sign-up, puis revient sur https://linkdash.dev/device avec le code de la CLI pour que vous puissiez l’approuver. Vous avez déjà un compte ? auth login ouvre /device. En mode headless, définissez LINKDASH_TOKEN avec un jeton de session obtenu via auth create ou auth login. N’inventez pas de jetons.
Fichier de session : ~/.config/linkdash/config.json (mode 0600).
La CLI ne peut pas modifier l’e-mail, le mot de passe ni la facturation. Redirigez l’utilisateur vers le tableau de bord. Clés d’API (HTTP et MCP) : Clés d’API.
Commandes
linkdash <command> [options]
| Commande | Rôle |
|---|---|
auth create |
Inscription dans le navigateur, puis approbation de l’appareil |
auth login |
Connexion de l’appareil via le navigateur |
auth logout |
Oublier la session enregistrée |
auth whoami |
JSON du compte connecté |
links list |
Lister les liens et les dossiers, page par page (--limit, --cursor) |
links get <id> |
Un lien |
links create --url <url> |
Lien court à partir d’une URL |
links create --file <path> |
Téléverser un fichier et obtenir un lien |
links create --text <text> |
Enregistrer un extrait |
links create --folder <name> |
Créer un dossier |
links create --variant <name> … |
Lien avec plusieurs variantes (répartition / ciblage) |
links update <id> |
Modifier la destination, le fichier, le mot de passe, l’expiration, le domaine, le statut, l’affectation persistante (sticky) ou les paramètres transmis |
links move <id> --in <folder-id> |
Placer un lien ou un dossier dans un dossier (--root pour le niveau racine) |
links copy <id> |
Créer une copie avec un nouveau slug, dans le même dossier |
links delete <id> |
Supprimer un lien (les éléments d’un dossier remontent d’un niveau ; --with-contents les supprime) |
links share <id> --email <email> |
Partager avec des personnes par e-mail (répétez --email ; --role editor leur permet de modifier l’élément ; chaque nouvelle personne reçoit un e-mail d’invitation) |
links unshare <id> --email <email> |
Retirer l’accès d’une personne |
links shares [id] |
Qui, à part vous, peut l’ouvrir, y compris via un dossier parent. Sans id : tout ce à quoi vous avez invité des personnes, page par page (--limit, --cursor) |
links shared |
Ce que d’autres personnes ont partagé avec vous, page par page (--limit, --cursor) |
links leave <_id | share URL> |
Renoncer à un élément partagé avec vous |
links role <id> --email <e> --role viewer|editor |
Faire d’une personne invitée un lecteur ou un éditeur |
links unlock <_id | share URL> |
Saisir le mot de passe d’un élément partagé pour voir et modifier sa cible pendant 30 minutes |
links activity <id> |
Qui a modifié un élément, et comment |
links reset-link <id> |
Nouvelle URL de partage ; l’ancienne URL linkdash.dev/s/ cesse de fonctionner |
links stats <id> |
Totaux de visites, de téléchargements et de lectures, également par variante, ainsi que les crawlers |
links export |
Afficher tous les liens au format CSV (une ligne par variante) |
links import <file> |
Importer des lignes URL et texte depuis un CSV |
links variants list <id> |
Variantes d’un lien |
links variants add <id> --name <n> |
Ajouter une variante |
links variants update <id> <name> |
Modifier une variante |
links variants remove <id> <name> |
Supprimer une variante |
webhooks list |
Lister les endpoints de webhook (secret masqué) |
webhooks get <id> |
Afficher l’URL d’un webhook (secret masqué) |
webhooks create --url <https> |
Ajouter un endpoint HTTPS (secret affiché une seule fois) |
webhooks rotate <id> |
Émettre un nouveau secret de signature |
webhooks delete <id> |
Supprimer un webhook |
domains list |
Lister les noms d’hôte personnalisés |
domains add <host> |
Ajouter un nom d’hôte (1 avec l’offre Free) |
domains connect <host> |
URL d’application Domain Connect, ou null |
domains verify <host> |
Vérifier le DNS avec Unkey |
domains remove <host> |
Supprimer un nom d’hôte |
-h, --help |
Aide (texte brut) |
-v, --version |
Version |
Si le même slug existe sur deux domaines du propriétaire, passez --domain.
Options de création et de mise à jour
Le slug est l’identifiant du lien, et aussi son chemin public lorsque le lien est public. Le nom n’est visible que par vous. Les nouveaux liens sont restreints (voir Accès et partage). La création accepte exactement un élément parmi --url, --file ou --text (qui devient la variante main), des blocs --variant (voir Variantes) ou --folder <name> (voir Dossiers).
| Option | Remarques |
|---|---|
--url <url> |
URL de destination |
--file <path> |
Fichier à téléverser (à la création, ou pour remplacer le contenu lors d’une mise à jour) |
--text <text> |
Extrait |
--access <restricted|link|public> |
Qui peut l’ouvrir. Par défaut : restricted. Voir Accès et partage |
--reset-share-link |
Émettre une nouvelle URL de partage (mise à jour uniquement) |
--slug <id> |
Chemin public : a-z0-9 et tirets internes, 1–64 caractères |
--name <label> |
Libellé privé |
--tag <tag> |
Répétable. En minuscules, sans virgules. 20 maximum |
--starts <when> |
Mise en ligne après 7d, 24h, 30m ou à une date ISO |
--password <secret> |
Exiger ce mot de passe pour l’ouvrir |
--expires <when> |
Cesser de le servir après 7d, 24h, 30m ou à une date ISO |
--max-openings <n> |
Mettre en pause après ce nombre d’ouvertures. Omettez cette option pour un nombre illimité |
--domain <host> |
Servir sur cet hôte au lieu de lida.sh |
--in <folder-id> |
Créer dans ce dossier (création uniquement ; --in-domain <host> si le slug du dossier existe plusieurs fois) |
--status <active|paused> |
Mettre en pause ou réactiver (mise à jour uniquement) |
--sticky / --no-sticky |
Un visiteur qui revient conserve la même variante (sticky par défaut) |
--restart-split |
Redistribuer les affectations persistantes (mise à jour uniquement) |
--forward-params / --no-forward-params |
Ajouter la query string du visiteur aux variantes URL (désactivé par défaut). Voir Transmettre les paramètres de requête |
--variant <name> |
Démarrer un bloc de variante (création uniquement). Voir Variantes |
--weight <n> --when <key=v1,v2> |
Par variante. Voir Variantes et Règles sur les paramètres de requête |
--preview-name <text> |
Nom public de l’aperçu (unfurl) |
--preview-description <text> |
Description publique de l’aperçu |
--preview-image <path> |
Image publique de l’aperçu |
--utm-source --utm-medium --utm-campaign --utm-term --utm-content |
Liens URL uniquement |
--clear-password --clear-expires --clear-starts --clear-tags --clear-preview --clear-name --clear-max-openings |
Mise à jour uniquement |
--status n’accepte que active ou paused. Le statut expiré découle de --expires, et le statut planifié de --starts. La résolution publique renvoie not-found jusqu’au démarrage. Une fois la limite --max-openings atteinte, le lien se met en pause ; augmentez ce nombre, ou utilisez --clear-max-openings, pour le servir à nouveau. Les ouvertures déjà effectuées restent comptabilisées jusqu’à ce que vous modifiiez ou supprimiez la limite.
Les slugs lida.sh sont partagés entre tous les utilisateurs. Si un mot est déjà pris, ajoutez un domaine personnalisé et réessayez avec --domain. Un lien sur un domaine personnalisé n’est pas publié en plus sur lida.sh.
Options de liste
Affiche une page, {items, cursor} : --limit est compris entre 1 et 100 (50 par défaut) ; passez à --cursor le cursor de la page précédente jusqu’à ce qu’il vaille null. Une page peut contenir moins d’éléments que --limit lorsqu’un filtre en écarte certains. --q recherche des mots entiers, le dernier étant traité comme un préfixe (laun trouve example.com/launch), avec un tri par pertinence ; --in liste un seul dossier, en commençant par les dossiers ; sinon, les éléments les plus récents apparaissent en premier.
| Option | Remarques |
|---|---|
--limit <n> |
Éléments par page, 1-100 (50 par défaut) |
--cursor <c> |
Le cursor de la page précédente |
--q <text> |
Rechercher des mots dans le nom, le slug, les noms et cibles des variantes, les noms de fichiers, le texte des extraits et les tags |
--tag <tag> |
Filtrer par tag |
--kind <url|file|text|folder|group> |
Filtrer par type (group = plusieurs variantes) |
--status <status> |
active, paused, expired, scheduled ou mixed |
--in <folder-id|root> |
Uniquement ce qui se trouve directement dans ce dossier, ou au niveau racine. Sans cette option, tout est listé |
Variantes
Chaque lien contient une ou plusieurs variantes. Une variante se compose d’un contenu (URL, fichier ou texte), de ses propres conditions d’accès (--password, --starts, --expires, --max-openings), d’un --weight et, éventuellement, de conditions sur le visiteur (--when). Sans --variant, un lien possède une seule variante nommée main, et toutes les commandes ci-dessus s’appliquent à elle. Chaque visiteur reçoit une variante : les variantes dont le --when correspond forment le pool (si aucune ne correspond, ce sont les variantes sans condition), puis une variante est tirée au sort selon les poids. Avec l’affectation persistante (par défaut), un visiteur qui revient conserve la même variante. Les conditions d’accès du lien priment sur celles des variantes. Noms de variantes : lettres minuscules, chiffres, tirets internes, 1–40 caractères, uniques au sein d’un lien. 20 variantes maximum.
Le kind du lien est celui de la variante s’il n’y en a qu’une, et group s’il y en a plusieurs. Le status du lien est celui défini par ses conditions d’accès lorsqu’elles s’appliquent (paused, scheduled, expired), sinon le statut commun à toutes les variantes, sinon mixed. variantStatuses compte {active, paused, expired, scheduled}.
Créer avec des blocs de 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> démarre un bloc de variante. Les options qui suivent s’appliquent à cette variante jusqu’au prochain --variant : --url|--file|--text, --password, --starts, --expires, --max-openings, --weight <n>, --when <key=v1,v2> (répétable), --utm-*. Les options du lien (--slug --name --tag --domain --preview-* --password --starts --expires --max-openings --sticky --no-sticky --forward-params) se placent avant le premier --variant.
Sous-commandes de variantes
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> accepte une option parmi --url, --file et --text, ainsi que les options de conditions d’accès, --weight, --when et --utm-*. variants update <id> <name> accepte --name <new>, les options de contenu et de conditions d’accès, --status active|paused, --weight, --when, --clear-when, --clear-password, --clear-starts, --clear-expires et --clear-max-openings. Un lien conserve toujours au moins une variante.
Clés --when
| Clé | Champ JSON | Valeurs |
|---|---|---|
country |
countries |
Codes 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 |
correspondance par préfixe (de, en-us) |
referrer |
referrerHosts |
suffixe d’hôte (twitter.com) |
Toutes les clés définies doivent correspondre. --when country=DE,AT --when device=mobile équivaut à { "countries": ["DE","AT"], "devices": ["mobile"] }.
Règles sur les paramètres de requête
--when accepte aussi des règles param: qui portent sur la query string du visiteur (lida.sh/promo?src=newsletter). Les clés sont sensibles à la casse, les valeurs sont comparées à l’identique, avec 10 règles maximum par variante. Comme les virgules servent de séparateur dans --when, une valeur de paramètre ne peut pas contenir de virgule ; utilisez | pour les listes.
| Syntaxe | op JSON |
Correspond lorsque |
|---|---|---|
param:KEY=VALUE |
equals |
la valeur est exactement VALUE |
param:KEY!=VALUE |
notEquals |
la valeur est différente, ou la clé est absente |
param:KEY~=VALUE |
includes |
la valeur contient VALUE |
param:KEY^=VALUE |
startsWith |
la valeur commence par VALUE |
param:KEY$=VALUE |
endsWith |
la valeur se termine par VALUE |
param:KEY=v1|v2 |
in |
la valeur fait partie de la liste |
param:KEY? or param:KEY |
exists |
la clé est présente |
param:!KEY |
missing |
la clé est absente |
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?"
Format JSON : "when": { "params": [{ "key": "src", "op": "equals", "value": "newsletter" }] } (value est omis pour exists / missing). Les valeurs des paramètres sont évaluées à l’ouverture du lien et ne sont jamais stockées dans les statistiques.
Transmettre les paramètres de requête
--forward-params / --no-forward-params sur links create et links update (au niveau du lien, désactivé par défaut) ajoute l’intégralité de la query string du visiteur aux variantes URL : lida.sh/promo?src=nl ouvre https://example.com/?src=nl. Les valeurs du visiteur remplacent celles enregistrées, y compris --utm-*. Les variantes fichier et texte ignorent ce réglage. Il s’agit de routage, et non de contrôle d’accès : n’importe qui peut ajouter des paramètres. Les valeurs des paramètres ne sont pas stockées dans les statistiques. links get affiche ce réglage sous la forme forwardParams.
Affectation persistante et redémarrage de la répartition
links update <id> --sticky / --no-sticky détermine si un visiteur qui revient conserve la même variante. links update <id> --restart-split redistribue les affectations persistantes. Les options de contenu de links update ne fonctionnent que pour les liens à variante unique ; sinon, utilisez links variants update <id> <name>.
Dossiers
Un dossier est un lien qui liste les éléments que vous y placez. Consultez Dossiers pour savoir comment fonctionnent la page publique et l’accès.
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> définit le nom du dossier (et non --name) et accepte --slug, --domain, --password, --starts, --expires, --max-openings, --tag, --preview-* et --in. Cette option ne peut pas être combinée avec --url, --file, --text ou --variant. links move affiche {id, folder}. links copy conserve le niveau d’accès, mais la copie reçoit une nouvelle URL de partage ; les personnes ne sont pas copiées. Sur un dossier, links delete fait remonter ses éléments d’un niveau ; avec --with-contents, ils sont supprimés eux aussi. Les lignes renvoyées par list, get et create incluent folder (le slug du dossier parent, ou null) ; les lignes de dossier incluent aussi items.
Accès et partage
Les nouveaux liens et dossiers sont restricted : leur url est https://linkdash.dev/s/<token>, que seuls vous et les personnes avec qui vous les partagez pouvez ouvrir, après connexion. --access link rend cette URL accessible à toute personne qui la possède. --access public sert le lien à son URL courte (lida.sh/<slug> ou votre domaine personnalisé). Utilisez --access public pour les liens que vous publiez. Le slug reste l’identifiant pour toutes les commandes, et son URL courte reste réservée tant que le lien n’est pas public. Consultez Partage et accès pour une description complète du modèle.
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
| Commande | Affiche |
|---|---|
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 (sans id) |
{items: [{id, name?, kind, access, url, people: [{email, accepted, invitedAt}]}], cursor}, les plus récemment partagés en premier |
links shared |
{items: [{_id, _creationTime, kind, title?, status, hasPassword, access, url, itemCount?, sharedBy?, sharedAt}], cursor}, les plus récents en premier |
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> (ou links update <id> --reset-share-link) |
{id, access, url} |
--role editor fait d’une personne un éditeur. Elle peut modifier l’élément et consulter ses statistiques, mais pas les mots de passe, le slug, le domaine, l’accès ni le partage. Elle ne peut pas non plus supprimer, déplacer ou copier l’élément, et une cible protégée par mot de passe nécessite d’abord links unlock (30 minutes). Les éditeurs utilisent l’_id ou l’URL de partage renvoyés par links shared. Toutes ces commandes acceptent --domain <host> lorsque le slug existe plusieurs fois. Dans la sortie de create, get, list, update, copy et share, url est l’URL de partage, sauf si le lien est public, auquel cas il s’agit de l’URL courte ; les lignes incluent access. Les limites sont de 200 personnes par élément, 50 e-mails par appel et 100 e-mails d’invitation par compte et par jour. Les deux listes affichent une page à la fois : --limit est compris entre 1 et 100 (50 par défaut) ; passez à --cursor la valeur de la page précédente jusqu’à ce que cursor vaille null. links leave accepte l’_id ou l’url renvoyés par links shared ; l’accès obtenu via un dossier parent partagé est conservé. Un partage, un retrait de partage, un changement d’accès et une réinitialisation comptent chacun comme un événement, mais pas le fait de quitter un partage.
Statistiques
linkdash links stats <id> --last 24h
--last est une durée (24h, 7d). Par défaut : 24h. Le JSON inclut visits, downloads, plays, visitsInLast, countries, referrers, variants (totaux par variante), visitors (chacun avec sa variant) et crawlers ([{crawler, company, category, hits, lastSeen}] : les bots et générateurs d’aperçus de liens qui ont récupéré le lien, jamais comptés comme des visites).
CSV
Colonnes : slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access. Une ligne par variante. kind, status, url, text, fileName, weight et when (chaîne JSON) sont propres à chaque variante ; les autres colonnes concernent le lien et se répètent. folder est le slug du dossier qui contient le lien. access vaut restricted, link ou public. L’export ne contient ni mots de passe, ni jetons de partage, ni personnes.
linkdash links export > links.csv
linkdash links import links.csv
L’import regroupe les lignes par slug + domaine. La première ligne crée le lien avec sa variante ; les lignes suivantes ajoutent des variantes. Pour un lien existant, la première ligne met à jour les champs du lien, puis chaque ligne met à jour la variante portant ce nom si elle existe, ou l’ajoute sinon. Les lignes de fichier sans contenu sont ignorées et produisent une erreur pour la ligne concernée. Les lignes où kind = folder (avec un name) créent des dossiers ; une fois toutes les lignes créées, la colonne folder place chaque lien dans son dossier. Si access est vide, les nouveaux liens sont restreints et les liens existants restent inchangés.
Exemples
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
Voir aussi dossiers, partage et accès, webhooks et domaines personnalisés.

