CLI
从 npm 安装 linkdash-cli,然后运行 `linkdash` 命令。命令成功时在 stdout 输出 JSON。帮助信息和错误以纯文本形式输出到 stderr。
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。MCP:MCP。Agent 技能:Agent 技能。价格:价格。纯 Markdown 版本:cli.md。
没有 --json 标志。出错时退出码为 1。
认证
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 无法修改邮箱、密码或账单信息。请引导用户前往控制台。API 密钥(用于 HTTP 和 MCP):API 密钥。
命令
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> |
创建文件夹 |
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> |
通过邮箱与他人共享(可重复 --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,当链接公开时也是其公开路径。名称仅你自己可见。新链接默认为受限访问(参见访问与共享)。创建时必须且只能指定以下其中一项:--url、--file 或 --text(它将成为变体 main)、--variant 块(参见变体),或 --folder <name>(参见文件夹)。
| 标志 | 说明 |
|---|---|
--url <url> |
目标 URL |
--file <path> |
要上传的文件(创建时使用,或在更新时替换文件内容) |
--text <text> |
文本片段 |
--access <restricted|link|public> |
谁可以打开。默认为 restricted。参见访问与共享 |
--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 变体上(默认关闭)。参见转发查询参数 |
--variant <name> |
开始一个变体块(仅创建时可用)。参见变体 |
--weight <n> --when <key=v1,v2> |
按变体设置。参见变体和查询参数规则 |
--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 是共用的。如果某个词已被占用,请添加自定义域名并使用 --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} 的数量。
使用变体块创建
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 之前。
变体子命令
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 |
该键不存在 |
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>。
文件夹
文件夹是一种链接,用于列出你放入其中的项目。公开页面和访问权限的工作方式请参见文件夹。
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,在链接未公开期间,其短链接也会保持预留。完整模型请参见共享与访问。
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;通过上级共享文件夹获得的访问权限仍会保留。共享、取消共享、访问权限变更和重置各计为一个事件;离开不计入。
统计
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。不包含密码、共享令牌或共享成员。
linkdash links export > links.csv
linkdash links import links.csv
导入时按 slug + 域名对行进行分组。第一行创建链接及其变体;后续行添加更多变体。对于已存在的链接,第一行会更新链接字段,然后每一行按名称更新已存在的变体,不存在则添加。没有文件内容的文件行会被跳过,并返回该行的错误。kind = folder 的行(需带 name)会创建文件夹;在所有行都创建完成后,folder 列会将每个链接放入对应的文件夹。access 为空时,新链接为受限访问,已存在的链接保持不变。
示例
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

