跳到内容
所有文章

climcpapi

面向开发者和 AI 智能体的短链接 CLI

用 Linkdash CLI 在命令行中缩短 URL:分享文件和文本片段、做 A/B 测试、定向访客,还能让 AI 智能体通过 MCP 管理链接。

Igor Kirnosov阅读约需 17 分钟

在终端中用 linkdash links create 命令创建 Linkdash 短链接

Linkdash 是一个可以在终端中操作的短链接服务。一条命令就能把 URL、文件或文本片段变成 lida.sh 上可追踪的短链接,并以 JSON 输出结果,方便你通过管道传给任何程序。同样的操作也可以通过 HTTP API 和 MCP 服务器完成,因此 AI 智能体可以用与你完全相同的工具来创建、更新和衡量链接。

本指南会完整介绍这个 CLI:安装、缩短第一个链接、分享文件、限制链接访问、运行 A/B 测试、按国家/地区或设备路由访客,以及无需打开浏览器即可查看数据分析。

Linkdash 控制台列出了短链接及其类型、后缀、目标和状态

安装 Linkdash CLI

CLI 是一个 npm 包,需要 Node.js 20 或更高版本。

npm i -g linkdash-cli

用 pnpm add -g linkdash-cli 或 bun add -g linkdash-cli 安装效果相同。安装后的命令是 linkdash。

然后一步完成账户创建和 CLI 登录:

linkdash auth create

这会在浏览器中打开注册页面。有了账户之后,批准终端中显示的代码,CLI 就登录好了。如果你已经有账户,请改用 linkdash auth login。linkdash auth whoami 可以确认你正在使用哪个账户,CLI 参考文档列出了所有命令和参数。

会话保存在 ~/.config/linkdash/config.json 中,权限仅限所有者。在 CI 或其他无界面环境中,把 LINKDASH_TOKEN 设为你在已登录机器上该文件中的会话令牌,并像对待其他机密一样妥善保管。

在命令行中缩短 URL

linkdash links create --url https://example.com/pricing --slug pricing
{
  "id": "pricing",
  "url": "https://lida.sh/pricing",
  "kind": "url",
  "variants": [
    { "name": "main", "kind": "url" }
  ]
}

这就是全部接口:命令成功时在 stdout 输出 JSON,出错时在 stderr 输出纯文本,退出码为 1。没有 --json 参数,因为 JSON 是唯一的输出格式。这让 CLI 很容易写进脚本。在 macOS 上,把新生成的短链接直接复制到剪贴板:

linkdash links create --url https://example.com/pricing | jq -r .url | pbcopy

几个你会经常用到的参数:

  • --slug 设置公开路径。后缀可使用小写字母、数字和中间的连字符,最长 64 个字符。不指定时,Linkdash 会自动生成一个。
  • --name 是仅你可见的私有标签,便于以后查找链接。
  • --tag 可以重复使用,--tag launch --tag q4 会给链接打上两个标签。
  • --utm-source、--utm-medium、--utm-campaign、--utm-term 和 --utm-content 会为目标地址添加活动参数。

用 linkdash links list --q pricing --tag launch 列出和搜索你创建的链接。

分享文件或文本片段

短链接不只适用于 URL。同一个命令也可以上传文件或保存文本片段:

linkdash links create --file ./board-deck.pdf --slug board-deck --expires 7d
linkdash links create --text "Release checklist: tag, build, smoke test, announce" --tag launch

文件链接为访客提供下载,图片和视频还支持预览。文本链接会在页面上显示该片段,并附带复制按钮。两者都和其他链接一样会被追踪,所以你能看到谁在什么时候打开了你的演示文稿。要在不改变 URL 的情况下替换现有链接背后的文件:

linkdash links update board-deck --file ./board-deck-v2.pdf

控制谁能打开链接

每个链接都可以有自己的访问规则:

linkdash links create --url https://example.com/decks/q4-2026 \
  --slug q4-deck \
  --password "$DECK_PASSWORD" \
  --expires 14d \
  --max-openings 50
  • --password 要求访客在打开链接前输入密码。
  • --starts 和 --expires 接受 30m、24h、7d 这样的时长,或 ISO 格式的日期。在开始时间之前,链接完全无法访问。
  • --max-openings 会在打开达到指定次数后暂停链接,适合一次性下载。

你可以随时用 linkdash links update q4-deck --status paused 和 --status active 暂停和恢复链接。

对短链接做 A/B 测试

在 Linkdash 中,每个链接都是一个或多个变体的容器。变体是一个目标(URL、文件或文本),有自己的权重和规则。普通链接只有一个名为 main 的变体。添加更多变体后,短链接就会在它们之间分流流量:

linkdash links create --slug launch \
  --variant control --url https://example.com/pricing \
  --variant annual-first --url "https://example.com/pricing?view=annual"

每个 --variant 之后的参数都属于该变体,直到出现下一个 --variant。流量按权重分配,默认权重为 1,所以上面的例子是一个 50/50 测试。给某个变体设置 --weight 3,它获得的流量就是其他变体的三倍。

默认采用固定分配:回访的访客会一直看到同一个变体,这正是公平测试所需要的。修改实验后,运行 linkdash links update launch --restart-split 可以让所有人重新分配一次。

一个包含 control 和 annual-first 两个变体的 Linkdash 链接,在两个价格页面之间分流流量

统计数据按变体返回,可以直接对比:

linkdash links stats launch --last 7d

输出中的 variants 数组会报告每个变体的 visits、visitors、downloads 和 plays。统计数据的更多内容见下文。

按国家/地区、设备或查询参数路由访客

变体还可以设置条件。为变体加上 --when 后,只有符合条件的访客才会分到它。这样一个短链接就变成了一个路由器。例如,一个把手机用户引导到对应应用商店的链接:

linkdash links create --slug get-app \
  --variant ios \
    --url https://apps.apple.com/app/example/id000000000 \
    --when os=ios \
  --variant android \
    --url "https://play.google.com/store/apps/details?id=com.example" \
    --when os=android \
  --variant web \
    --url https://example.com/app

访客打开链接时,条件匹配的变体组成候选池。如果没有匹配的变体,就改用没有条件的变体,所以上面的 web 会接住所有不是 iOS 或 Android 的访客。

一个 Linkdash 链接:iOS 用户跳转到 App Store,Android 用户跳转到 Google Play,其他人跳转到网页

可以匹配的字段:

键 匹配内容 示例
country ISO 国家/地区代码 --when country=DE,AT,CH
device mobile、tablet、desktop --when device=mobile
os windows、macos、android、ios、linux、other --when os=ios
browser edge、chrome、firefox、safari、other --when browser=safari
language 语言标签,按前缀匹配 --when language=de
referrer 来源域名 --when referrer=twitter.com

重复使用 --when 可以同时要求多个条件。--when country=DE,AT --when device=mobile 会匹配来自德国或奥地利的移动端访客。

变体还可以匹配访客的查询字符串,这样同一个链接可以根据你分享的位置表现出不同的行为。lida.sh/launch?src=newsletter 可以把邮件订阅读者引导到专门的页面:

linkdash links variants add launch --name newsletter \
  --url https://example.com/pricing/newsletter \
  --when param:src=newsletter

参数规则支持等于(=)、不等于(!=)、包含(~=)、开头是(^=)、结尾是($=)、属于其中之一(=a|b)、存在(param:ref?)和不存在(param:!ref)。如果你希望把访客的参数原样传递到目标地址,请在创建链接时加上 --forward-params。

控制台中也有相同的控件,还提供可按名称搜索的国家/地区选择器,所以你不必记住斯洛文尼亚的代码是 SI:

在 Linkdash 控制台中为变体选择目标国家/地区,已选中德国和奥地利

在终端中读取点击分析

linkdash links stats launch --last 7d

输出包括 visits、downloads 和 plays 的总数,你所查询时间窗口内的访问次数(visitsInLast),这些访问来自的 countries 和 referrers,按变体划分的 variants 明细,以及一个 visitors 列表,其中包含每次最近访问的时间、国家/地区、设备、浏览器和来源。--last 接受 24h 或 30d 这样的时长,默认为 24h。

Linkdash 不存储访客的 IP 地址。该地址仅用于查询访客所在的国家/地区,并生成一个每天变化的匿名访客标识符,之后即被丢弃。

如果想在点击发生时实时响应,可以注册一个 Webhook。Linkdash 会向任意 HTTPS 端点发送带签名的 link.visit、link.download 和 link.play 事件:

linkdash webhooks create --url https://example.com/hooks

签名密钥只显示一次,请立即保存。验证签名的方法请参阅 Webhook 文档。

让 AI 智能体通过 MCP 创建短链接

以上所有功能 AI 智能体也都能使用。Linkdash 在 https://api.linkdash.dev/mcp 运行一个远程 MCP 服务器,其工具与 CLI 一一对应:links_create、links_update、links_stats、variants_add、domains_add 等,返回的 JSON 也完全相同。

在控制台的 API 密钥 中创建一个 API 密钥,然后连接你的智能体。在 Claude Code 中:

claude mcp add --transport http linkdash https://api.linkdash.dev/mcp \
  --header "Authorization: Bearer $LINKDASH_API_KEY"

在 Cursor 中,将其添加到 .cursor/mcp.json:

{
  "mcpServers": {
    "linkdash": {
      "url": "https://api.linkdash.dev/mcp",
      "headers": { "Authorization": "Bearer ${env:LINKDASH_API_KEY}" }
    }
  }
}

在 Codex 中,它会从你指定的环境变量中读取密钥:

codex mcp add linkdash --url https://api.linkdash.dev/mcp \
  --bearer-token-env-var LINKDASH_API_KEY

之后,你就可以用自然语言请求链接,例如“把 https://example.com/pricing 缩短为 pricing 并打上 launch 标签”,或者“这周 launch 的哪个变体访客更多?”,智能体会调用正确的工具。MCP 文档还介绍了 OpenCode 的配置。

如果你的智能体本来就在终端中工作,它可以直接使用 CLI。安装 Linkdash 智能体技能,让它了解所有命令和参数:

npx skills add https://linkdash.dev/skills/linkdash/SKILL.md

使用 HTTP API

在你自己的代码中,同样的操作以普通 REST API 的形式提供,地址为 https://api.linkdash.dev/v1,使用同一个 API 密钥认证:

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer $LINKDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/pricing", "slug": "pricing" }'

响应的结构与 CLI 输出相同。API 参考文档涵盖了所有端点,包括文件上传和变体。

使用你自己的域名

短链接默认位于 lida.sh。如果想改用你自己的域名,先添加域名,再把 DNS 指向 Linkdash:

linkdash domains add go.example.com
linkdash domains verify go.example.com

然后用 --domain go.example.com 在该域名上创建链接。每个自定义域名都有自己独立的后缀集合,所以 go.example.com/launch 不会与其他人的 launch 冲突。域名指南介绍了 DNS 设置,包括对支持的服务商提供的一键配置。

价格

免费套餐无需信用卡,每月包含 5,000 个事件、1 GB 文件存储、一个月的数据分析历史以及一个自定义域名。事件是指你的链接上发生的一次访问、下载或播放,或是一次写入操作,例如创建或更新链接。列出链接、获取统计数据等读取操作是免费的。

付费套餐会提高这些额度:专业版每月 $18,增长版每月 $48。完整对比请参阅价格。

常见问题

有带 CLI 的免费短链接服务吗?

有。Linkdash CLI 在免费套餐中即可使用,每月包含 5,000 个事件,无需信用卡。

可以在 CI 中使用 Linkdash CLI 吗?

可以。把 LINKDASH_TOKEN 设为会话令牌,CLI 就能在没有浏览器的情况下运行。由于每条命令都输出 JSON,你可以在 GitHub Actions 或其他任何流水线中创建和更新链接,并用 jq 读取结果。

AI 智能体能创建短链接吗?

能,有三种方式:通过 https://api.linkdash.dev/mcp 上的 MCP 服务器,通过安装了 Linkdash 智能体技能的 CLI,或者通过 HTTP API。三者提供相同的操作,返回相同的 JSON。

Linkdash 会存储访客的 IP 地址吗?

不会。Linkdash 只用该地址查询访客所在的国家/地区并生成每日匿名标识符,然后就将其丢弃。链接所有者永远看不到 IP 地址。

一个短链接能把不同的访客引导到不同的页面吗?

能。给链接设置多个变体,并为每个变体添加国家/地区、设备、操作系统、语言、来源或查询参数等条件。没有条件时,变体会按权重分流流量,这就是做 A/B 测试的方式。


准备好试试了吗?安装 CLI,运行 linkdash auth create,一分钟内就能缩短你的第一个链接。快速入门中有完整步骤。

Linkdash

© 2026 Igor Kirnosov s.p. 保留所有权利。