CLI

Install linkdash-cli from npm, then run the `linkdash` command. Successful commands print JSON on stdout. Help and errors are plain text on stderr.

npm i -g linkdash-cli
# or: pnpm add -g linkdash-cli / bun add -g linkdash-cli / npx linkdash-cli@latest

The npm package is linkdash-cli. The command is linkdash.

HTTP equivalent: HTTP API. MCP: MCP. Agent skill: Agent skill. Pricing: Pricing. Plain markdown: cli.md.

There is no --json flag. Exit code 1 on errors.

Auth

linkdash auth create
linkdash auth login
linkdash auth whoami
linkdash auth logout

No account yet? auth create opens https://linkdash.dev/sign-up, then returns to https://linkdash.dev/device with the CLI code so you can approve. Already have an account? auth login opens /device. Headless: set LINKDASH_TOKEN to a session token from auth create or auth login. Do not invent tokens.

Session file: ~/.config/linkdash/config.json (mode 0600).

The CLI cannot change email, password, or billing. Send the user to the dashboard. API keys (HTTP and MCP): API keys.

Commands

linkdash <command> [options]

If the same slug exists on two of the owner’s domains, pass --domain.

Create and update flags

Slug is the public path. Name is only visible to you. Create takes exactly one of --url, --file, or --text (that becomes the variant main), or --variant blocks (see Variants).

--status only accepts active or paused. Expired comes from --expires. Scheduled comes from --starts. Public resolve is not-found until start. After --max-openings is reached the link pauses; raise the number, or --clear-max-openings, to serve it again. Openings already used stay counted until you change or remove the limit.

lida.sh slugs are shared. If a word is taken, add a custom domain and retry with --domain. A branded-domain link does not also publish on lida.sh.

List flags

Variants

Every link is a container of one or more variants. A variant is the content (URL, file, or text) plus its own gate (--password, --starts, --expires, --max-openings), a --weight, and optional visitor conditions (--when). Without --variant a link has one variant named main, and every command above is shorthand for it. A visitor gets one variant: variants whose --when matches form the pool (if none match, the unconditional variants do), then a weighted pick. With sticky assignment (default) a returning visitor keeps the same variant. The link’s own gate wins over variant gates. Variant names: lowercase letters, digits, internal hyphens, 1–40 chars, unique per link. Max 20 variants.

Link kind is the variant’s kind for one variant and group for several. Link status is the link gate when set (paused, scheduled, expired), else the shared variant status, else mixed. variantStatuses counts {active, paused, expired, scheduled}.

Create with variant blocks

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> starts a variant block. Flags after it belong to that variant until the next --variant: --url|--file|--text, --password, --starts, --expires, --max-openings, --weight <n>, --when <key=v1,v2> (repeatable), --utm-*. Link flags (--slug --name --tag --domain --preview-* --password --starts --expires --max-openings --sticky --no-sticky --forward-params) go before the first --variant.

Variant subcommands

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> takes one of --url, --file, --text, plus gate flags, --weight, --when, --utm-*. variants update <id> <name> takes --name <new>, content, gate flags, --status active|paused, --weight, --when, --clear-when, --clear-password, --clear-starts, --clear-expires, --clear-max-openings. A link keeps at least one variant.

--when keys

Every set key must match. --when country=DE,AT --when device=mobile is { "countries": ["DE","AT"], "devices": ["mobile"] }.

Query parameter rules

--when also takes param: rules on the visitor’s query string (lida.sh/promo?src=newsletter). Keys are case-sensitive, values compare exactly, max 10 rules per variant. Commas split --when, so a param value cannot contain a comma; use | for lists.

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

JSON shape: "when": { "params": [{ "key": "src", "op": "equals", "value": "newsletter" }] } (value is omitted for exists / missing). Parameter values are matched at open time and never stored in analytics.

Forward query parameters

--forward-params / --no-forward-params on links create and links update (link-level, off by default) appends the visitor’s whole query string to URL variants: lida.sh/promo?src=nl opens https://example.com/?src=nl. Visitor values override stored ones, --utm-* included. File and text variants ignore it. This is routing, not access control: anyone can add parameters. Parameter values are not stored in analytics. links get shows it as forwardParams.

Sticky and restart split

links update <id> --sticky / --no-sticky sets whether a returning visitor keeps the same variant. links update <id> --restart-split reshuffles sticky assignments. Content flags on links update work only for single-variant links; otherwise use links variants update <id> <name>.

Stats

linkdash links stats <id> --last 24h

--last is a duration (24h, 7d). Default 24h. JSON includes visits, downloads, plays, visitsInLast, countries, referrers, variants (per-variant totals), and visitors (each with variant).

CSV

Columns: slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created. One row per variant. kind, status, url, text, fileName, weight, and when (JSON string) are per variant; the rest are per link and repeat. No passwords.

linkdash links export > links.csv
linkdash links import links.csv

Import groups rows by slug + domain. The first row creates the link with its variant; more rows add variants. For an existing link the first row updates the link fields, then each row updates the variant by name if it exists, else adds it. File rows without bytes are skipped with a per-row error.

Examples

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

See also webhooks and custom domains.