---
title: CLI
description: >-
  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.
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
```

O pacote npm é `linkdash-cli`. O comando é `linkdash`.

Equivalente HTTP: [API HTTP](/pt/api). MCP: [MCP](/pt/mcp). Skill de agente: [Skill de agente](/pt/skill). Preços: [Preços](/pt/pricing). Markdown simples: [cli.md](https://linkdash.dev/cli.md).

Não existe a flag `--json`. Código de saída 1 em caso de erro.

## Autenticação

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

## 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](/pt/folders) |
| `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](/pt/sharing) 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](#access-and-sharing)). A criação aceita **exatamente um** de `--url`, `--file` ou `--text` (que se torna a variante `main`), blocos `--variant` (consulte [Variantes](#variants)) ou `--folder <name>` (consulte [Pastas](#folders)).

| 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](#access-and-sharing) |
| `--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](#forward-query-parameters) |
| `--variant <name>` | Iniciar um bloco de variante (apenas na criação). Consulte [Variantes](#variants) |
| `--weight <n>` `--when <key=v1,v2>` | Por variante. Consulte [Variantes](#variants) e [Regras de parâmetros de consulta](#query-parameter-rules) |
| `--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](/pt/domains) 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

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

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

```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?"
```

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](/pt/folders) para saber como funcionam a página pública e o acesso.

```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>` 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](/pt/sharing) para conhecer o modelo 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 | 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

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

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

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

Consulte também [pastas](/pt/folders), [partilha e acesso](/pt/sharing), [webhooks](/pt/webhooks) e [domínios personalizados](/pt/domains).
