CLI
Instale o linkdash-cli a partir do npm e execute o comando `linkdash`. Os comandos bem-sucedidos imprimem JSON no stdout. A ajuda e os erros são texto simples no stderr.
npm i -g linkdash-cli
# or: pnpm add -g linkdash-cli / bun add -g linkdash-cli / npx linkdash-cli@latest
O pacote npm é linkdash-cli. O comando é linkdash.
Equivalente HTTP: API HTTP. MCP: MCP. Skill de agente: Skill de agente. Preços: Preços. Markdown simples: cli.md.
Não existe a flag --json. Código de saída 1 em caso de erro.
Autenticação
linkdash auth create
linkdash auth login
linkdash auth whoami
linkdash auth logout
Ainda não tem conta? auth create abre https://linkdash.dev/sign-up e depois regressa a https://linkdash.dev/device com o código da CLI, para aprovação. Já tem conta? auth login abre /device. Sem interface gráfica (headless): defina LINKDASH_TOKEN com um token de sessão obtido através de auth create ou auth login. Não invente tokens.
Ficheiro de sessão: ~/.config/linkdash/config.json (modo 0600).
A CLI não pode alterar o email, a palavra-passe nem a faturação. Encaminhe o utilizador para o painel. Chaves de API (HTTP e MCP): Chaves de API.
Comandos
linkdash <command> [options]
| Comando | O que faz |
|---|---|
auth create |
Registo no browser, seguido de aprovação do dispositivo |
auth login |
Início de sessão no browser através do dispositivo |
auth logout |
Esquecer a sessão guardada |
auth whoami |
JSON da conta com sessão iniciada |
links list |
Listar links e pastas, uma página de cada vez (--limit, --cursor) |
links get <id> |
Um link |
links create --url <url> |
Link curto a partir de um URL |
links create --file <path> |
Carregar um ficheiro e obter um link |
links create --text <text> |
Guardar um excerto de texto |
links create --folder <name> |
Criar uma pasta |
links create --variant <name> … |
Link com várias variantes (divisão / segmentação) |
links update <id> |
Alterar o destino, o ficheiro, a palavra-passe, a expiração, o domínio, o estado, a fixação (sticky) ou os parâmetros reencaminhados |
links move <id> --in <folder-id> |
Colocar um link ou uma pasta numa pasta (--root para o nível superior) |
links copy <id> |
Criar uma cópia com um novo slug, na mesma pasta |
links delete <id> |
Eliminar um link (os itens de uma pasta sobem um nível; --with-contents elimina-os) |
links share <id> --email <email> |
Partilhar com pessoas por email (repita --email; --role editor permite-lhes alterá-lo; cada pessoa nova recebe um email de convite) |
links unshare <id> --email <email> |
Remover o acesso de alguém |
links shares [id] |
Quem, além de si, o pode abrir, incluindo através de uma pasta acima. Sem id: tudo aquilo para que convidou pessoas, uma página de cada vez (--limit, --cursor) |
links shared |
O que outras pessoas partilharam consigo, uma página de cada vez (--limit, --cursor) |
links leave <_id | share URL> |
Abdicar de algo partilhado consigo |
links role <id> --email <e> --role viewer|editor |
Tornar alguém que convidou leitor ou editor |
links unlock <_id | share URL> |
Introduzir a palavra-passe de um item partilhado para ver e editar o respetivo destino durante 30 minutos |
links activity <id> |
Quem alterou um item e de que forma |
links reset-link <id> |
Novo URL de partilha; o URL antigo linkdash.dev/s/ deixa de funcionar |
links stats <id> |
Totais de visitas, transferências e reproduções, também por variante, além de crawlers |
links export |
Imprimir todos os links em CSV (uma linha por variante) |
links import <file> |
Importar linhas de URL e de texto a partir de CSV |
links variants list <id> |
Variantes de um link |
links variants add <id> --name <n> |
Adicionar uma variante |
links variants update <id> <name> |
Alterar uma variante |
links variants remove <id> <name> |
Remover uma variante |
webhooks list |
Listar endpoints de webhook (segredo mascarado) |
webhooks get <id> |
Mostrar o URL de um webhook (segredo mascarado) |
webhooks create --url <https> |
Adicionar um endpoint HTTPS (segredo mostrado uma única vez) |
webhooks rotate <id> |
Emitir um novo segredo de assinatura |
webhooks delete <id> |
Remover um webhook |
domains list |
Listar nomes de anfitrião personalizados |
domains add <host> |
Adicionar um nome de anfitrião (1 no plano Free) |
domains connect <host> |
URL de aplicação do Domain Connect, ou null |
domains verify <host> |
Verificar o DNS com o Unkey |
domains remove <host> |
Remover um nome de anfitrião |
-h, --help |
Ajuda (texto simples) |
-v, --version |
Versão |
Se o mesmo slug existir em dois domínios do proprietário, passe --domain.
Flags de criação e atualização
O slug é o id do link e o respetivo caminho público quando o link é público. O nome só é visível para si. Os links novos são restritos (consulte Acesso e partilha). A criação aceita exatamente um de --url, --file ou --text (que se torna a variante main), blocos --variant (consulte Variantes) ou --folder <name> (consulte Pastas).
| Flag | Notas |
|---|---|
--url <url> |
URL de destino |
--file <path> |
Ficheiro a carregar (na criação, ou para substituir os bytes na atualização) |
--text <text> |
Excerto de texto |
--access <restricted|link|public> |
Quem o pode abrir. Predefinição: restricted. Consulte Acesso e partilha |
--reset-share-link |
Emitir um novo URL de partilha (apenas na atualização) |
--slug <id> |
Caminho público: a-z0-9 e hífenes internos, 1–64 |
--name <label> |
Rótulo privado |
--tag <tag> |
Repetível. Minúsculas, sem vírgulas. Máximo de 20 |
--starts <when> |
Ativar após 7d, 24h, 30m ou uma data ISO |
--password <secret> |
Exigir esta palavra-passe para abrir |
--expires <when> |
Deixar de servir após 7d, 24h, 30m ou uma data ISO |
--max-openings <n> |
Pausar após este número de aberturas. Omitir para ilimitado |
--domain <host> |
Servir neste anfitrião em vez de lida.sh |
--in <folder-id> |
Criar dentro desta pasta (apenas na criação; --in-domain <host> se o slug da pasta se repetir) |
--status <active|paused> |
Pausar ou retomar (apenas na atualização) |
--sticky / --no-sticky |
O visitante que regressa mantém a mesma variante (predefinição: fixo) |
--restart-split |
Baralhar novamente as atribuições fixas (apenas na atualização) |
--forward-params / --no-forward-params |
Acrescentar a query string do visitante às variantes de URL (desativado por predefinição). Consulte Reencaminhar parâmetros de consulta |
--variant <name> |
Iniciar um bloco de variante (apenas na criação). Consulte Variantes |
--weight <n> --when <key=v1,v2> |
Por variante. Consulte Variantes e Regras de parâmetros de consulta |
--preview-name <text> |
Nome público da pré-visualização (unfurl) |
--preview-description <text> |
Descrição pública da pré-visualização |
--preview-image <path> |
Imagem pública da pré-visualização |
--utm-source --utm-medium --utm-campaign --utm-term --utm-content |
Apenas links de URL |
--clear-password --clear-expires --clear-starts --clear-tags --clear-preview --clear-name --clear-max-openings |
Apenas na atualização |
--status só aceita active ou paused. O estado expirado resulta de --expires. O estado agendado resulta de --starts. A resolução pública devolve not-found até ao início. Quando --max-openings é atingido, o link entra em pausa; aumente o número, ou use --clear-max-openings, para voltar a servi-lo. As aberturas já utilizadas continuam contabilizadas até alterar ou remover o limite.
Os slugs de lida.sh são partilhados. Se uma palavra estiver ocupada, adicione um domínio personalizado e tente novamente com --domain. Um link num domínio personalizado não é publicado também em lida.sh.
Flags de listagem
Imprime uma página, {items, cursor}: --limit vai de 1 a 100 (predefinição 50); passe --cursor com o cursor da página anterior até este ser null. Uma página pode conter menos itens do que --limit quando um filtro exclui alguns. --q procura palavras inteiras, sendo a última tratada como prefixo (laun encontra example.com/launch), com os resultados ordenados por relevância; --in lista uma pasta, com as pastas primeiro; caso contrário, aparecem primeiro os mais recentes.
| Flag | Notas |
|---|---|
--limit <n> |
Itens por página, 1-100 (predefinição 50) |
--cursor <c> |
O cursor da página anterior |
--q <text> |
Pesquisar palavras no nome, slug, nomes e destinos das variantes, nomes de ficheiros, texto dos excertos e etiquetas |
--tag <tag> |
Filtrar por etiqueta |
--kind <url|file|text|folder|group> |
Filtrar por tipo (group = várias variantes) |
--status <status> |
active, paused, expired, scheduled ou mixed |
--in <folder-id|root> |
Apenas o que está diretamente nesta pasta, ou no nível superior. Sem esta flag, é listado tudo |
Variantes
Cada link é um contentor de uma ou mais variantes. Uma variante é o conteúdo (URL, ficheiro ou texto) mais a sua própria restrição (--password, --starts, --expires, --max-openings), um --weight e condições de visitante opcionais (--when). Sem --variant, um link tem uma única variante chamada main, e todos os comandos acima são uma forma abreviada para essa variante. Cada visitante recebe uma variante: as variantes cujo --when corresponde formam o conjunto de candidatas (se nenhuma corresponder, usam-se as variantes incondicionais), seguindo-se uma escolha ponderada. Com atribuição fixa (predefinição), um visitante que regressa mantém a mesma variante. A restrição do próprio link prevalece sobre as restrições das variantes. Nomes de variantes: letras minúsculas, dígitos, hífenes internos, 1–40 caracteres, únicos por link. Máximo de 20 variantes.
O kind do link é o tipo da variante quando existe uma só variante e group quando existem várias. O status do link é a restrição do link quando definida (paused, scheduled, expired); caso contrário, o estado comum das variantes; caso contrário, mixed. variantStatuses contabiliza {active, paused, expired, scheduled}.
Criar com blocos 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> inicia um bloco de variante. As flags que se seguem pertencem a essa variante até ao próximo --variant: --url|--file|--text, --password, --starts, --expires, --max-openings, --weight <n>, --when <key=v1,v2> (repetível), --utm-*. As flags do link (--slug --name --tag --domain --preview-* --password --starts --expires --max-openings --sticky --no-sticky --forward-params) são colocadas antes do primeiro --variant.
Subcomandos 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> aceita um de --url, --file ou --text, mais flags de restrição, --weight, --when e --utm-*. variants update <id> <name> aceita --name <new>, conteúdo, flags de restrição, --status active|paused, --weight, --when, --clear-when, --clear-password, --clear-starts, --clear-expires e --clear-max-openings. Um link mantém sempre pelo menos uma variante.
Chaves de --when
| Chave | Campo JSON | Valores |
|---|---|---|
country |
countries |
Códigos 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 |
correspondência por prefixo (de, en-us) |
referrer |
referrerHosts |
sufixo do anfitrião (twitter.com) |
Todas as chaves definidas têm de corresponder. --when country=DE,AT --when device=mobile equivale a { "countries": ["DE","AT"], "devices": ["mobile"] }.
Regras de parâmetros de consulta
--when também aceita regras param: aplicadas à query string do visitante (lida.sh/promo?src=newsletter). As chaves distinguem maiúsculas de minúsculas, os valores são comparados de forma exata, com um máximo de 10 regras por variante. As vírgulas separam os valores de --when, pelo que um valor de parâmetro não pode conter vírgulas; use | para listas.
| Sintaxe | op JSON |
Corresponde quando |
|---|---|---|
param:KEY=VALUE |
equals |
o valor é exatamente VALUE |
param:KEY!=VALUE |
notEquals |
o valor é diferente, ou a chave está ausente |
param:KEY~=VALUE |
includes |
o valor contém VALUE |
param:KEY^=VALUE |
startsWith |
o valor começa por VALUE |
param:KEY$=VALUE |
endsWith |
o valor termina em VALUE |
param:KEY=v1|v2 |
in |
o valor é um dos da lista |
param:KEY? ou param:KEY |
exists |
a chave está presente |
param:!KEY |
missing |
a chave está ausente |
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?"
Formato JSON: "when": { "params": [{ "key": "src", "op": "equals", "value": "newsletter" }] } (value é omitido para exists / missing). Os valores dos parâmetros são avaliados no momento da abertura e nunca são guardados nos dados de análise.
Reencaminhar parâmetros de consulta
--forward-params / --no-forward-params em links create e links update (ao nível do link, desativado por predefinição) acrescenta toda a query string do visitante às variantes de URL: lida.sh/promo?src=nl abre https://example.com/?src=nl. Os valores do visitante substituem os valores guardados, incluindo os de --utm-*. As variantes de ficheiro e de texto ignoram esta opção. Trata-se de encaminhamento, não de controlo de acesso: qualquer pessoa pode adicionar parâmetros. Os valores dos parâmetros não são guardados nos dados de análise. links get mostra esta opção como forwardParams.
Fixação e reinício da divisão
links update <id> --sticky / --no-sticky define se um visitante que regressa mantém a mesma variante. links update <id> --restart-split baralha novamente as atribuições fixas. As flags de conteúdo em links update só funcionam em links com uma única variante; caso contrário, use links variants update <id> <name>.
Pastas
Uma pasta é um link que lista os itens nela colocados. Consulte Pastas para saber como funcionam a página pública e o acesso.
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> define o nome da pasta (não --name) e aceita --slug, --domain, --password, --starts, --expires, --max-openings, --tag, --preview-* e --in. Não pode ser combinada com --url, --file, --text nem --variant. links move imprime {id, folder}. links copy mantém o nível de acesso, mas recebe um novo URL de partilha; as pessoas não são copiadas. links delete aplicado a uma pasta move os respetivos itens um nível acima; --with-contents elimina-os também. As linhas devolvidas por list, get e create incluem folder (o slug da pasta que contém o item, ou null); as linhas de pastas incluem também items.
Acesso e partilha
Os links e as pastas novos são restricted: o respetivo url é https://linkdash.dev/s/<token>, que só o próprio e as pessoas com quem partilha podem abrir, com sessão iniciada. --access link torna esse URL acessível a qualquer pessoa que o tenha. --access public serve o link no respetivo URL curto (lida.sh/<slug> ou o seu domínio personalizado). Use --access public para links que publique abertamente. O slug continua a ser o id em todos os comandos, e o respetivo URL curto permanece reservado enquanto o link não for público. Consulte Partilha e acesso para conhecer o modelo 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 | Imprime |
|---|---|
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 (sem id) |
{items: [{id, name?, kind, access, url, people: [{email, accepted, invitedAt}]}], cursor}, partilhados mais recentemente primeiro |
links shared |
{items: [{_id, _creationTime, kind, title?, status, hasPassword, access, url, itemCount?, sharedBy?, sharedAt}], cursor}, mais recentes primeiro |
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 torna alguém editor: pode alterar o item e ver as respetivas estatísticas, mas não pode ver nem alterar palavras-passe, slug, domínio, acesso ou partilha, nem eliminar, mover ou copiar, e um destino protegido por palavra-passe exige primeiro links unlock (30 minutos). Os editores usam o _id ou o URL de partilha devolvido por links shared. Todos aceitam --domain <host> quando o slug se repete. O url na saída de create, get, list, update, copy e share é o URL de partilha, exceto se o link for público, caso em que é o URL curto; as linhas incluem access. Até 200 pessoas por item, 50 emails por chamada e 100 emails de convite por conta por dia. As duas listas imprimem uma página: --limit vai de 1 a 100 (predefinição 50); passe --cursor da página anterior até cursor ser null. links leave aceita o _id ou o url devolvido por links shared; o acesso através de uma pasta partilhada acima mantém-se. Partilhar, deixar de partilhar, uma alteração de acesso e uma reposição contam, cada um, como um evento; sair não conta.
Estatísticas
linkdash links stats <id> --last 24h
--last é uma duração (24h, 7d). Predefinição: 24h. O JSON inclui visits, downloads, plays, visitsInLast, countries, referrers, variants (totais por variante), visitors (cada um com variant) e crawlers ([{crawler, company, category, hits, lastSeen}]: bots e pré-visualizações de links que obtiveram o link, nunca contabilizados como visitas).
CSV
Colunas: slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access. Uma linha por variante. kind, status, url, text, fileName, weight e when (string JSON) são por variante; as restantes são por link e repetem-se. folder é o slug da pasta onde o link se encontra. access é restricted, link ou public. Não inclui palavras-passe, tokens de partilha nem pessoas.
linkdash links export > links.csv
linkdash links import links.csv
A importação agrupa as linhas por slug + domínio. A primeira linha cria o link com a respetiva variante; as linhas seguintes adicionam variantes. Para um link existente, a primeira linha atualiza os campos do link e, em seguida, cada linha atualiza a variante com o mesmo nome, se existir, ou adiciona-a caso contrário. As linhas de ficheiro sem bytes são ignoradas, com um erro por linha. As linhas com kind = folder (com um name) criam pastas; a coluna folder coloca cada link na respetiva pasta depois de todas as linhas existirem. Um access vazio torna os links novos restritos e deixa os links existentes inalterados.
Exemplos
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
Consulte também pastas, partilha e acesso, webhooks e domínios personalizados.

