---
title: CLI
description: >-
  从 npm 安装 linkdash-cli，然后运行 `linkdash` 命令。命令成功时在 stdout 输出
  JSON。帮助信息和错误以纯文本形式输出到 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
```

npm 包名为 `linkdash-cli`，命令为 `linkdash`。

对应的 HTTP 接口：[HTTP API](/zh/api)。MCP：[MCP](/zh/mcp)。Agent 技能：[Agent 技能](/zh/skill)。价格：[价格](/zh/pricing)。纯 Markdown 版本：[cli.md](https://linkdash.dev/cli.md)。

没有 `--json` 标志。出错时退出码为 1。

## 认证

```bash
linkdash auth create
linkdash auth login
linkdash auth whoami
linkdash auth logout
```

还没有账号？`auth create` 会打开 https://linkdash.dev/sign-up，注册完成后返回 https://linkdash.dev/device 并带上 CLI 代码，供你确认授权。已有账号？`auth login` 会打开 `/device`。无头环境：将 `LINKDASH_TOKEN` 设置为通过 `auth create` 或 `auth login` 获得的会话令牌。不要自行编造令牌。

会话文件：`~/.config/linkdash/config.json`（权限模式 0600）。

CLI 无法修改邮箱、密码或账单信息。请引导用户前往[控制台](https://linkdash.dev/dashboard/billing)。API 密钥（用于 HTTP 和 MCP）：[API 密钥](https://linkdash.dev/dashboard/keys)。

## 命令

```
linkdash <command> [options]
```

| 命令 | 作用 |
| --- | --- |
| `auth create` | 在浏览器中注册，然后进行设备授权 |
| `auth login` | 通过浏览器进行设备登录 |
| `auth logout` | 清除已保存的会话 |
| `auth whoami` | 当前登录账号的 JSON |
| `links list` | 分页列出链接和文件夹（`--limit`、`--cursor`） |
| `links get <id>` | 获取单个链接 |
| `links create --url <url>` | 根据 URL 创建短链接 |
| `links create --file <path>` | 上传文件并获取链接 |
| `links create --text <text>` | 保存一段文本片段 |
| `links create --folder <name>` | 创建[文件夹](/zh/folders) |
| `links create --variant <name> …` | 创建包含多个变体的链接（分流 / 定向） |
| `links update <id>` | 修改目标地址、文件、密码、过期时间、域名、状态、粘性分配或参数转发 |
| `links move <id> --in <folder-id>` | 将链接或文件夹移入某个文件夹（`--root` 表示移到顶层） |
| `links copy <id>` | 在同一文件夹中创建副本，使用新的 slug |
| `links delete <id>` | 删除链接（文件夹中的项目会上移一级；`--with-contents` 会一并删除） |
| `links share <id> --email <email>` | 通过邮箱与他人[共享](/zh/sharing)（可重复 `--email`；`--role editor` 允许对方修改；每位新成员都会收到邀请邮件） |
| `links unshare <id> --email <email>` | 移除某人的访问权限 |
| `links shares [id]` | 除你之外还有谁能打开它，包括通过上级文件夹获得权限的人。不传 id 时：分页列出你邀请过他人的所有内容（`--limit`、`--cursor`） |
| `links shared` | 分页列出他人共享给你的内容（`--limit`、`--cursor`） |
| `links leave <_id \| share URL>` | 放弃他人共享给你的内容 |
| `links role <id> --email <e> --role viewer\|editor` | 将你邀请的某人设为查看者或编辑者 |
| `links unlock <_id \| share URL>` | 输入共享项目的密码，在 30 分钟内查看和编辑其目标 |
| `links activity <id>` | 查看谁修改了项目以及如何修改 |
| `links reset-link <id>` | 生成新的共享 URL；旧的 `linkdash.dev/s/` URL 失效 |
| `links stats <id>` | 访问、下载和播放总数（也按变体统计），以及爬虫信息 |
| `links export` | 以 CSV 格式输出所有链接（每个变体一行） |
| `links import <file>` | 从 CSV 导入 URL 和文本行 |
| `links variants list <id>` | 列出链接的变体 |
| `links variants add <id> --name <n>` | 添加变体 |
| `links variants update <id> <name>` | 修改变体 |
| `links variants remove <id> <name>` | 删除变体 |
| `webhooks list` | 列出 webhook 端点（密钥已遮盖） |
| `webhooks get <id>` | 显示单个 webhook URL（密钥已遮盖） |
| `webhooks create --url <https>` | 添加 HTTPS 端点（密钥仅显示一次） |
| `webhooks rotate <id>` | 生成新的签名密钥 |
| `webhooks delete <id>` | 删除 webhook |
| `domains list` | 列出自定义主机名 |
| `domains add <host>` | 添加主机名（Free 套餐限 1 个） |
| `domains connect <host>` | Domain Connect 应用 URL，或 null |
| `domains verify <host>` | 通过 Unkey 检查 DNS |
| `domains remove <host>` | 删除主机名 |
| `-h, --help` | 帮助（纯文本） |
| `-v, --version` | 版本 |

如果同一个 slug 存在于所有者的两个域名上，请传入 `--domain`。

## 创建和更新标志

slug 是链接的 id，当链接公开时也是其公开路径。名称仅你自己可见。新链接默认为受限访问（参见[访问与共享](#access-and-sharing)）。创建时**必须且只能**指定以下其中一项：`--url`、`--file` 或 `--text`（它将成为变体 `main`）、`--variant` 块（参见[变体](#variants)），或 `--folder <name>`（参见[文件夹](#folders)）。

| 标志 | 说明 |
| --- | --- |
| `--url <url>` | 目标 URL |
| `--file <path>` | 要上传的文件（创建时使用，或在更新时替换文件内容） |
| `--text <text>` | 文本片段 |
| `--access <restricted\|link\|public>` | 谁可以打开。默认为 `restricted`。参见[访问与共享](#access-and-sharing) |
| `--reset-share-link` | 生成新的共享 URL（仅更新时可用） |
| `--slug <id>` | 公开路径：`a-z0-9` 及中间的连字符，长度 1–64 |
| `--name <label>` | 私有标签 |
| `--tag <tag>` | 可重复。小写，不含逗号。最多 20 个 |
| `--starts <when>` | 在 `7d`、`24h`、`30m` 后或指定 ISO 日期生效 |
| `--password <secret>` | 打开时需要输入此密码 |
| `--expires <when>` | 在 `7d`、`24h`、`30m` 后或指定 ISO 日期停止服务 |
| `--max-openings <n>` | 达到此打开次数后暂停。省略则不限次数 |
| `--domain <host>` | 在此主机上提供服务，而非 `lida.sh` |
| `--in <folder-id>` | 在此文件夹内创建（仅创建时可用；如果文件夹 slug 重复，使用 `--in-domain <host>`） |
| `--status <active\|paused>` | 暂停或恢复（仅更新时可用） |
| `--sticky` / `--no-sticky` | 回访者保持同一变体（默认开启粘性） |
| `--restart-split` | 重新打乱粘性分配（仅更新时可用） |
| `--forward-params` / `--no-forward-params` | 将访问者的查询字符串追加到 URL 变体上（默认关闭）。参见[转发查询参数](#forward-query-parameters) |
| `--variant <name>` | 开始一个变体块（仅创建时可用）。参见[变体](#variants) |
| `--weight <n>` `--when <key=v1,v2>` | 按变体设置。参见[变体](#variants)和[查询参数规则](#query-parameter-rules) |
| `--preview-name <text>` | 公开预览卡片名称 |
| `--preview-description <text>` | 公开预览卡片描述 |
| `--preview-image <path>` | 公开预览卡片图片 |
| `--utm-source` `--utm-medium` `--utm-campaign` `--utm-term` `--utm-content` | 仅适用于 URL 链接 |
| `--clear-password` `--clear-expires` `--clear-starts` `--clear-tags` `--clear-preview` `--clear-name` `--clear-max-openings` | 仅更新时可用 |

`--status` 只接受 `active` 或 `paused`。过期状态由 `--expires` 决定，计划状态由 `--starts` 决定。在开始时间之前，公开解析会返回 not-found。达到 `--max-openings` 后链接会暂停；调高该数值或使用 `--clear-max-openings` 即可重新提供服务。已使用的打开次数会一直计入，直到你修改或移除该限制。

`lida.sh` 的 slug 是共用的。如果某个词已被占用，请添加[自定义域名](/zh/domains)并使用 `--domain` 重试。品牌域名上的链接不会同时发布到 `lida.sh`。

## 列表标志

每次输出一页，格式为 `{items, cursor}`：`--limit` 取值 1-100（默认 50）；将上一页返回的 `cursor` 通过 `--cursor` 传入，直到它为 `null`。当过滤条件跳过部分项目时，一页的项目数可能少于 `--limit`。`--q` 按完整单词匹配，最后一个单词按前缀匹配（`laun` 可匹配 `example.com/launch`），结果按相关性排序；`--in` 列出单个文件夹的内容，文件夹排在前面；其他情况按最新优先排序。

| 标志 | 说明 |
| --- | --- |
| `--limit <n>` | 每页项目数，1-100（默认 50） |
| `--cursor <c>` | 上一页返回的 `cursor` |
| `--q <text>` | 在名称、slug、变体名称和目标、文件名、文本片段内容及标签中搜索单词 |
| `--tag <tag>` | 按标签过滤 |
| `--kind <url\|file\|text\|folder\|group>` | 按类型过滤（`group` = 包含多个变体） |
| `--status <status>` | `active`、`paused`、`expired`、`scheduled` 或 `mixed` |
| `--in <folder-id\|root>` | 仅列出直接位于此文件夹或顶层中的内容。不传则列出全部 |

## 变体

每个链接都是一个或多个**变体**的容器。变体包含内容（URL、文件或文本），以及其自身的访问条件（`--password`、`--starts`、`--expires`、`--max-openings`）、`--weight` 和可选的访问者条件（`--when`）。不使用 `--variant` 时，链接只有一个名为 `main` 的变体，上面的所有命令都是针对它的简写。每位访问者只会得到一个变体：`--when` 匹配的变体组成候选池（若都不匹配，则使用无条件的变体），然后按权重选取。启用粘性分配（默认）时，回访者会保持同一变体。链接自身的访问条件优先于变体的访问条件。变体名称：小写字母、数字及中间的连字符，1–40 个字符，在同一链接内唯一。最多 20 个变体。

链接的 `kind` 在只有一个变体时为该变体的类型，有多个变体时为 `group`。链接的 `status` 在设置了链接级访问条件时取其值（`paused`、`scheduled`、`expired`），否则取所有变体共同的状态，否则为 `mixed`。`variantStatuses` 统计 `{active, paused, expired, scheduled}` 的数量。

### 使用变体块创建

```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>` 开始一个变体块。其后的标志都属于该变体，直到下一个 `--variant`：`--url|--file|--text`、`--password`、`--starts`、`--expires`、`--max-openings`、`--weight <n>`、`--when <key=v1,v2>`（可重复）、`--utm-*`。链接级标志（`--slug --name --tag --domain --preview-* --password --starts --expires --max-openings --sticky --no-sticky --forward-params`）需放在第一个 `--variant` 之前。

### 变体子命令

```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>` 接受 `--url`、`--file`、`--text` 中的一项，以及访问条件标志、`--weight`、`--when`、`--utm-*`。`variants update <id> <name>` 接受 `--name <new>`、内容、访问条件标志、`--status active|paused`、`--weight`、`--when`、`--clear-when`、`--clear-password`、`--clear-starts`、`--clear-expires`、`--clear-max-openings`。链接至少保留一个变体。

### `--when` 键

| 键 | JSON 字段 | 取值 |
| --- | --- | --- |
| `country` | `countries` | 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` | 前缀匹配（`de`、`en-us`） |
| `referrer` | `referrerHosts` | 主机后缀（`twitter.com`） |

所有已设置的键都必须匹配。`--when country=DE,AT --when device=mobile` 对应 `{ "countries": ["DE","AT"], "devices": ["mobile"] }`。

### 查询参数规则

`--when` 还支持针对访问者查询字符串（`lida.sh/promo?src=newsletter`）的 `param:` 规则。键区分大小写，值按精确比较，每个变体最多 10 条规则。`--when` 使用逗号分隔，因此参数值不能包含逗号；列表请使用 `|`。

| 语法 | JSON `op` | 匹配条件 |
| --- | --- | --- |
| `param:KEY=VALUE` | `equals` | 值恰好为 `VALUE` |
| `param:KEY!=VALUE` | `notEquals` | 值不同，或该键不存在 |
| `param:KEY~=VALUE` | `includes` | 值包含 `VALUE` |
| `param:KEY^=VALUE` | `startsWith` | 值以 `VALUE` 开头 |
| `param:KEY$=VALUE` | `endsWith` | 值以 `VALUE` 结尾 |
| `param:KEY=v1\|v2` | `in` | 值为列表中的某一项 |
| `param:KEY?` 或 `param:KEY` | `exists` | 该键存在 |
| `param:!KEY` | `missing` | 该键不存在 |

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

JSON 结构：`"when": { "params": [{ "key": "src", "op": "equals", "value": "newsletter" }] }`（`exists` / `missing` 时省略 `value`）。参数值在打开时进行匹配，不会存储到分析数据中。

### 转发查询参数

`links create` 和 `links update` 上的 `--forward-params` / `--no-forward-params`（链接级，默认关闭）会将访问者的完整查询字符串追加到 URL 变体上：`lida.sh/promo?src=nl` 会打开 `https://example.com/?src=nl`。访问者传入的值会覆盖已存储的值，包括 `--utm-*`。文件和文本变体会忽略此设置。这是路由功能，而非访问控制：任何人都可以添加参数。参数值不会存储到分析数据中。`links get` 中以 `forwardParams` 显示。

### 粘性分配与重新分流

`links update <id> --sticky` / `--no-sticky` 设置回访者是否保持同一变体。`links update <id> --restart-split` 会重新打乱粘性分配。`links update` 上的内容标志仅适用于单变体链接；其他情况请使用 `links variants update <id> <name>`。

## 文件夹

文件夹是一种链接，用于列出你放入其中的项目。公开页面和访问权限的工作方式请参见[文件夹](/zh/folders)。

```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>` 用于设置文件夹名称（而非 `--name`），并接受 `--slug`、`--domain`、`--password`、`--starts`、`--expires`、`--max-openings`、`--tag`、`--preview-*` 和 `--in`。它不能与 `--url`、`--file`、`--text` 或 `--variant` 同时使用。`links move` 输出 `{id, folder}`。`links copy` 会保留访问级别，但会获得新的共享 URL；共享成员不会被复制。对文件夹执行 `links delete` 会将其中的项目上移一级；`--with-contents` 会将它们一并删除。list、get 和 create 的输出行包含 `folder`（所在文件夹的 slug，或 `null`）；文件夹行还包含 `items`。

## 访问与共享

新的链接和文件夹默认为 `restricted`：其 `url` 为 `https://linkdash.dev/s/<token>`，只有你和你共享的对象在登录后才能打开。`--access link` 允许任何持有该 URL 的人打开。`--access public` 通过短链接（`lida.sh/<slug>` 或你的自定义域名）提供服务。对于需要公开发布的链接，请使用 `--access public`。slug 在所有命令中始终是 id，在链接未公开期间，其短链接也会保持预留。完整模型请参见[共享与访问](/zh/sharing)。

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

| 命令 | 输出 |
| --- | --- |
| `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`（不传 id） | `{items: [{id, name?, kind, access, url, people: [{email, accepted, invitedAt}]}], cursor}`，按最近共享优先排序 |
| `links shared` | `{items: [{_id, _creationTime, kind, title?, status, hasPassword, access, url, itemCount?, sharedBy?, sharedAt}], cursor}`，按最新优先排序 |
| `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>`（或 `links update <id> --reset-share-link`） | `{id, access, url}` |

`--role editor` 会将某人设为编辑者：他们可以修改项目并查看其统计数据，但不能修改密码、slug、域名、访问权限、共享设置，也不能删除、移动或复制；对于受密码保护的目标，需要先执行 `links unlock`（有效期 30 分钟）。编辑者使用 `links shared` 中的 `_id` 或共享 URL。当 slug 重复时，所有命令都接受 `--domain <host>`。`create`、`get`、`list`、`update`、`copy` 和 `share` 输出中的 `url` 为共享 URL，链接公开时则为短链接；输出行包含 `access`。每个项目最多 200 人，每次调用最多 50 个邮箱，每个账号每天最多发送 100 封邀请邮件。这两个列表命令每次输出一页：`--limit` 取值 1-100（默认 50）；将上一页的 `cursor` 通过 `--cursor` 传入，直到 `cursor` 为 `null`。`links leave` 接受 `links shared` 中的 `_id` 或 `url`；通过上级共享文件夹获得的访问权限仍会保留。共享、取消共享、访问权限变更和重置各计为一个事件；离开不计入。

## 统计

```bash
linkdash links stats <id> --last 24h
```

`--last` 为时长（`24h`、`7d`），默认 `24h`。JSON 包含 `visits`、`downloads`、`plays`、`visitsInLast`、`countries`、`referrers`、`variants`（各变体总数）、`visitors`（每项包含 `variant`）以及 `crawlers`（`[{crawler, company, category, hits, lastSeen}]`：抓取过该链接的机器人和链接预览服务，从不计入访问次数）。

## CSV

列：`slug,kind,name,variant,url,text,fileName,status,domain,tags,starts,expires,maxOpenings,weight,when,created,folder,access`。每个变体一行。`kind`、`status`、`url`、`text`、`fileName`、`weight` 和 `when`（JSON 字符串）为变体级字段；其余为链接级字段，会重复出现。`folder` 是链接所在文件夹的 slug。`access` 为 `restricted`、`link` 或 `public`。不包含密码、共享令牌或共享成员。

```bash
linkdash links export > links.csv
linkdash links import links.csv
```

导入时按 slug + 域名对行进行分组。第一行创建链接及其变体；后续行添加更多变体。对于已存在的链接，第一行会更新链接字段，然后每一行按名称更新已存在的变体，不存在则添加。没有文件内容的文件行会被跳过，并返回该行的错误。`kind` = `folder` 的行（需带 `name`）会创建文件夹；在所有行都创建完成后，`folder` 列会将每个链接放入对应的文件夹。`access` 为空时，新链接为受限访问，已存在的链接保持不变。

## 示例

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

另请参阅[文件夹](/zh/folders)、[共享与访问](/zh/sharing)、[webhooks](/zh/webhooks) 和[自定义域名](/zh/domains)。
