命令参考

概述

TSLink 提供了一组简洁的命令来管理 Tailscale 网络上的服务。所有命令遵循 tslink <命令> [参数] [标志] 的模式。

认证

tslink login#

通过引导菜单录入并存储凭据。普通 login 不是浏览器 OAuth callback；单独的页面打开 helper 是另一项操作。

tslink login

非交互式模式（适用于 CI/CD 和自动化）：

# 通过 stdin（不把 secret 放进 argv 或 history）
printf %s "$TSLINK_API_KEY" | tslink login --api-key-stdin
printf %s "$TSLINK_CLIENT_SECRET" | tslink login --client-secret-stdin

# 通过 secret manager 预注入的环境变量
tslink login

选择恰好一个明确凭据来源（一个 stdin flag 或一个兼容 argv flag）；多个明确来源是 usage error。未指定明确来源时，先考虑环境变量，再进入交互提示。--json 禁用交互录入；自动化优先使用 stdin 或 secret manager 注入的环境，避免 argv/history 泄漏。

标志：

TSLink 接受两种密钥类型：

• API 访问令牌（tskey-api-*）— 输入时自动验证，tslink serve 时自动派生认证密钥。
• OAuth 客户端密钥（tskey-client-*）— 不会周期性过期，但当前 Tailscale REST 标签/设备自动化能力比 API-token 模式更窄。

凭据优先使用系统钥匙串（macOS Keychain、Linux Secret Service、Windows Credential Manager）。明文 0600 文件回退仅在 macOS/Linux 证明旧钥匙串值不存在或已删除后允许；钥匙串不可达或状态不确定时拒绝写入，应恢复访问后重试。Windows 不允许凭据文件回退。无头运行本身不保证可以回退。

API 令牌生成地址：管理后台 → Keys。OAuth 密钥生成地址：管理后台 → OAuth（点击 "+ credential" → "OAuth client" → 按所需 API 操作配置 scopes → 复制 client secret）。

API 访问令牌会过期，TSLink 会记录过期时间。传 --expires-in 或 --expires-at 时按你声明的值存储；两个都不传时，TSLink 按 90 天上限假定，并记录 expires_at_source=assumed_max，这样后续 tslink doctor 能区分「假定的期限」和「声明的期限」，而不会把猜测当成事实。

--open-keys-page 和 --open-oauth-page 是引导辅助命令，不是登录方式。只有当 stdin 是交互式终端且 CI 未设置时才真的打开浏览器，否则打印 URL 和引导步骤。两种情况下都以退出码 0 结束且不存储任何东西，因此可以安全地在「还在找凭证从哪来」的脚本里运行。

tslink logout#

清除 Tailscale 认证状态并移除已存储的凭证（API 密钥和/或 OAuth 客户端密钥）。在登出之前必须先停止网关。

tslink logout

这会从系统钥匙串中移除所有凭证（以及旧文件），并移除 ~/.config/tslink/ 中的节点状态。你的服务注册表（registry.json）会被保留。

Flags:

用 --kind 可以在保留另一个凭证继续可用的前提下退役其中一个，例如把自动化从 OAuth client secret 迁移到 API 访问令牌之后。

服务管理

tslink add <名称>#

默认 add 会确保后台网关运行，可能返回授权交接。完成授权后用 url --wait；不要在默认 add 后再启动另一个 serve。同名条目会被替换。

注册一个新服务以暴露到你的 tailnet。必须提供 --proxy、--dir 或 --tcp 之一。

服务类型标志：

行为标志：

其他标志：

示例：

# 暴露一个 Web 应用
tslink add webapp --proxy localhost:3000

# 暴露一个 API 服务器，带 ACL 标签
tslink add api --proxy 127.0.0.1:8080 --tags tag:api,tag:prod

# 暴露一个目录用于文件共享
tslink add docs --dir ~/Documents/shared

# 通过 TCP 暴露 PostgreSQL 数据库
tslink add mydb --tcp localhost:5432

# 请求临时节点；本地注册保留至主动移除
tslink add devserver --proxy :8080 --ephemeral

# 通过 Tailscale Funnel 公开访问
tslink add public-site --proxy localhost:3000 --funnel --public

# 限制特定用户访问
tslink add internal --proxy localhost:9090 --allow user@example.com,tag:admin

# 为该服务指定控制服务器
tslink add headscale-app --proxy localhost:3000 --control-url https://headscale.example.com

tslink remove <名称>#

按名称移除已注册的服务。本地 registry 移除会立即完成。本地 tsnet state 只有在远端身份被证明已清除后才删除；daemon 运行时由其 reconciliation 负责删除 state。远端 tailnet 清理只有在 TSLink 拥有匹配设备的精确所有权证明时才会尝试；否则匹配候选会报告为 protected，并跳过清理。

tslink remove webapp

remove 是幂等的。移除一个从未注册过的名字是一次成功调用，只是什么都没移除，所以要回答「服务是否已经没了」看 removed 而不是 ok：

{"type":"tslink.result","ok":true,"schema_version":1,"command":"remove","code":0,"data":{"name":"docs-example-nonexistent","removed":false,"device_cleaned":false,"device_cleanup_skipped":false}}

如果网关正在运行，服务将通过热重载移除，无需重启。

Flags:

幂等是清理脚本该有的默认行为：重跑第二遍不应该失败。--strict 面向相反的场景 —— 调用方希望「这个名字确实注册过」成为一个被强制检查的前置条件。

tslink list#

以表格格式显示所有已注册的服务，无论网关是否运行。

tslink list

输出列：

标志：

tslink list --tailnet#

默认列表读的是本机的 ~/.config/tslink/registry.json。--tailnet 改为查询 Tailscale API，报告 tailnet 中每一台带 TSLink 标签的设备：本机注册的服务、其它机器注册的服务，以及孤儿节点。它回答的是单机注册表回答不了的跨机器问题。

tslink list --tailnet
tslink list --tailnet --json

每一行都标明它来自机器边界的哪一侧：

人类可读输出以 N of M TSLink-owned tailnet devices are not registered on this machine. 结尾，JSON 负载在 count 之外还带 registered_count 与 unregistered_count。每个结果都带一个常量字段 cleanup_authority，因为这个视图暴露了一条真实的限制：tslink cleanup 只删除精确 NodeID 记录在本机 node-ownership.json 中的设备，所以本机注册表没有命名的设备，必须回到创建它的那台机器上清理。--tailnet 永远不输出 NodeID，也永远不删除任何东西。

--tailnet 需要已存储的 Tailscale API 凭证（tskey-api-* 访问令牌或 OAuth 客户端密钥）。没有凭证时它以 auth_error（退出码 3）失败，并在 error.next 中给出 bootstrap 指引；它不会返回空列表。它与 --name、--type、--fields、--verbose 互斥（usage_error，退出码 2），因为那些 flag 过滤的是本机已注册服务，而 --tailnet 报告的是 tailnet 设备。

tslink share <path|port|host:port>#

注册一个一次性的 proxy 或 file 服务，需要时启动 daemon，并等待一个精确的 runtime URL——这是从零到一个 URL 最快的路径。已存在的目录会作为 file 服务暴露其内容；普通文件只暴露选中的文件并返回该文件的 URL，不暴露同级文件或父目录列表；裸端口或 host:port 目标会变成 HTTP 代理。分享默认是临时（ephemeral）的，重复分享同一目标会复用已有服务，而不是创建带后缀的孤立节点。

tslink share ./build
tslink share ./report.html          # URL 直接指向 report.html
tslink share 3000
tslink share localhost:8080 --name preview
tslink share ./build --ephemeral=false

在零凭据首次运行时，stdout 只有一行——Tailscale 授权 URL，stderr 会打印出精确的续接命令（tslink url <name> --wait）。加 --json 时，这是一个成功的 status:"needs_login" 结果，携带 auth_url——不是认证错误。

标志：

tslink url <name>#

打印一个已注册服务的精确 runtime URL，可选择等待它就绪。

tslink url myapp
tslink url myapp --wait
tslink url myapp --wait --raw

标志：

如果 runtime 尚未报告精确的 tailnet 主机名，且你没有传 --wait，tslink url 会以非零状态退出，error.code 为 url_not_ready，而不是打印占位符。

网关

tslink serve#

启动 TSLink 网关。为每个已注册的服务启动一个嵌入式 tsnet 节点并开始服务。

标志：

# 在前台运行
tslink serve

# 作为后台守护进程运行
tslink serve --daemon

# 使用 Headscale 控制服务器（单次覆盖）
tslink serve --control-url https://headscale.example.com

启动时，TSLink 自动：

• 解析凭证并为每个服务启动一个 tsnet 节点。
• 使用 --manage-acl 和具有所需 scopes 的凭据配置普通 tag-owner policy。显式公开的 Funnel 默认配置共享 grant，除非 --no-auto-provision 或服务设置关闭。准确所有权设备清理是独立 API 操作。
• 监视 registry.json 的变化并热重载服务。

tslink stop#

停止正在运行的 TSLink 网关（前台或守护进程）。读取 tslink.pid 并验证进程属于 TSLink，最多等待 5 秒终止。macOS/Linux 使用 SIGTERM 正常关闭；Windows 使用进程终止，不是正常关闭。

stop 不会移除自动启动注册。受管理的 macOS LaunchAgent 启用了 KeepAlive，停止后会按 30 秒节流重启；需要持续停止时先执行 tslink uninstall。Linux systemd 用户服务的重启策略是 on-failure，成功的正常关闭会让它保持停止。Windows 的启动注册在卸载前仍会于下次登录生效。卸载后，停止任何剩余的手动网关，再用 tslink status --json 验证后才删除状态。

tslink stop

tslink status#

JSON 的 data.supervision 报告已验证的 manager、installed、autostart、restart_on_exit，以及可选 detail / evidence / autostart_scope。它与 daemon_running 分开；进程存活不证明自动启动或监督有效。

显示 TSLink 网关的当前状态：守护进程状态、认证状态和已注册服务数量。

tslink status

输出示例：

→ tslink: running (pid 12345)
→ tailnet: authenticated
→ services: 3 registered

Flags:

--urls 打印每个服务的可达位置。这是 owner-only 输出：它列出的端点就是你自己注册表里定义的那些，因此请按对待注册表本身的方式对待这份结果。

标签管理

tslink tags#

管理 TSLink 服务的 ACL 标签。API-key 模式可以通过 Tailscale API 创建或拉取标签；client-secret-only 模式不要在验证前依赖标签/设备自动化。

子命令：

tslink tags list#

列出所有已注册服务及其标签。

tslink tags list

tslink tags pull#

从 Tailscale API 打印当前 ACL 标签。 client-secret-only 模式会跳过该远端拉取，因为它需要 API 访问令牌。

tslink tags pull

tslink tags add <服务> <标签>#

为特定已注册服务添加标签。

tslink tags add webapp tag:staging

tslink tags set <服务> <标签>#

用一个标签替换特定服务的标签。

tslink tags set webapp tag:web

tslink tags set-default <标签>#

设置未指定 --tags 时应用于服务的默认标签。持久化在 GlobalConfig.DefaultTag 中。

# 将默认值从 tag:tsmain 更改为自定义标签
tslink tags set-default tag:myteam

tslink tags delete-remote <标签> --force --manage-acl#

通过本地安全检查后，经 API 从 Tailscale ACL 策略中全局移除 ACL 标签所有者规则。此操作会全局修改你的 tailnet ACL 策略，且远端 ACL mutation 默认关闭，因此必须同时显式传入 --force 和 --manage-acl。

tslink tags delete-remote tag:deprecated --force --manage-acl

维护

tslink cleanup#

对照本地 registry 与 tailnet：停用已过期 Funnel、删除本机具有准确所有权证明且不再需要的设备，并报告本机对共享 Funnel grant 的使用情况。永不删除共享 grant。

# 预览 -- 这是默认行为
tslink cleanup

# 实际执行
tslink cleanup --dry-run=false

Flags:

--dry-run 默认为 true，所以裸命令不删除任何东西。这个默认值是安全属性而不是便利性：删除要求持久化的精确 NodeID ownership proof，hostname 匹配仅用于发现。hostname 匹配上但 NodeID 未被证明的设备会出现在 devices_protected 里，永不删除。

--adopt 面向那些在 ownership proof 机制之前创建的设备。它只接受一个字面量 hostname，写入 proof 要求恰好一个 TSLink-tagged 远端匹配，外加 --force --dry-run=false；匹配多于一个时报 cardinality 冲突而不是替你猜。预览过程是只读的。

JSON envelope 会说明这次 cleanup 为什么什么都没做 —— 这比「它没做事」这个事实本身更重要：device_cleanup_skipped 配合 device_skip_reason 区分了 registry.json 结构上不可信、ownership ledger 不可用、orphan 缺少 retired_at provenance、没有可用的 API client、hostname-only 匹配受保护、以及远端清理失败这几种情况。输出中永远不出现 NodeID，只出现 hostname。

tslink registry#

直接检视本地服务注册表，不经过 runtime。

tslink registry check [path]#

严格校验一份 registry.json 并报告其中所有问题，且不修改文件。不带参数时校验当前生效的注册表；传路径则校验别处的文件，例如你正准备安装的候选文件，或来自另一台机器的副本。

tslink registry check
tslink registry check ./candidate-registry.json --json

返回结果包含 path、schema_version、valid_services、total_services，以及一个 issues[] 数组，其中每一项用 index 和 name 指名出问题的服务，并带稳定的 code 和给人读的 message。所有被拒绝的条目在一次调用中全部报出，因此 valid_services 小于 total_services 时，你能准确知道 runtime 会丢弃哪些服务、以及为什么，而不是只看到 loader 恰好最先撞上的那一个问题。

邀请

tslink invite#

邀请某个人加入你的 tailnet，或把某个 TSLink 拥有的服务设备共享给 tailnet 之外的人。

这里的每个子命令都会通过 Tailscale API 产生对外副作用：真实的人会收到真实的邀请。它们是 TSLink 中仅有的、效果能被你之外的人感知到的命令，因此每一条都显式指名收件人、要求由 tslink login 存储的 user-owned tskey-api- 令牌，并在 JSON envelope 中返回一个记录本次发送内容的 remote_side_effect_plan 对象。

设备共享还有第二重要求：TSLink 只共享它自己注册的设备，按精确 nodeId 匹配。无法证明归属的设备永远不会成为候选，因此打错服务名的结果是失败，而不是共享出一台不相干的机器。

子命令：

tslink invite user <email>#

邀请一个人加入你的 tailnet。

tslink invite user teammate@example.com
tslink invite user teammate@example.com --role auditor
tslink invite user teammate@example.com --print-link

--print-link 改变的是由谁送达邀请，不是谁可以接受邀请。JSON envelope 明确陈述送达事实而不是暗示它：Tailscale 发出邮件时 emailed: true，你自行送达时 emailed: false 并附带 invite_url。该 URL 由 Tailscale API 原样返回 -- TSLink 从不自行构造 -- 并且它是 bearer 凭证：谁持有谁就能接受。

tslink invite device <service> <email>#

把某个已注册服务背后的设备共享给外部用户，让对方无需加入你的 tailnet 就能访问那一台机器。

tslink invite device my-api partner@example.com
tslink invite device my-api partner@example.com --multi-use

--multi-use 和 --allow-exit-node 各自都会放大这份邀请授予的范围，各自都默认关闭。multi-use 邀请 URL 在第一次被接受之后仍然有效；exit-node 共享则允许接收方把自己的流量路由经过这台机器。

tslink invite list#

列出未接受的用户邀请，以及这个 TSLink 拥有的服务对应的设备邀请。

tslink invite list
tslink invite list --json

URL 默认不打印，因为它们是 bearer 凭证：打印一次就等于把一份可被接受的邀请放进你的终端回滚区，以及任何会捕获它的地方。

JSON envelope 把「空结果」和「不完整结果」区分开。complete: true 表示每个被请求的设备目标都无错误地检查过；false 表示有部分设备结果缺失。device_targets[] 携带逐服务的结果，因此一个已检查、invite_count: 0 的目标读作「没有未接受的邀请」，而不是「没查到」。

tslink invite revoke <id> --kind <user|device>#

撤销一个未接受的邀请。

tslink invite revoke 12345 --kind user

--kind 刻意没有默认值。用户邀请 ID 和设备邀请 ID 是两个独立的数字命名空间，同一个数字可以在两边各指向一个邀请；要求显式给出命名空间，是为了让目标是被指定的而不是被猜出来的。撤销设备邀请还要求精确的 TSLink 节点 ownership proof。只有在 Tailscale API 接受撤销之后才会出现 revoked: true。

tslink invite resend <id> --kind <user|device>#

重发一个最初以邮件方式创建的邀请。

tslink invite resend 12345 --kind user

用 --print-link 创建的邀请没有邮件地址，无法重发。重发输出也不会再次打印邀请 URL：把一份 bearer 凭证重印到第二个界面上没有任何收益，因此结果只报告 emailed 就停下。

诊断、访问解释与模板

tslink doctor#

运行本地诊断，并通过与其它命令相同的 JSON envelope 和退出码 contract 返回 warning/critical 阈值。

Flags:

两者默认关闭，因为两者都会伸到本进程之外：--probe-external 会向非 loopback 目标建立连接，--probe-remote 每个已存储凭证消耗一次 Tailscale API 调用。默认运行保持在本地且不产生费用。

Doctor 还会从本机 tailscaled 读取并报告本节点是否开启了 Tailscale SSH。人类可读输出打印 Tailscale SSH (this node): <state>；JSON 负载带有 tailscale_ssh.state 与 tailscale_ssh.acl_rule_required: true。这项检查存在的原因是：tailscale ssh <host> tslink <command> 是从 tailnet 内另一台机器操作这份安装的零代码路径，而这条路径需要两个都位于 Tailscale 层的条件：本节点开启了 Tailscale SSH，且 tailnet ACL 中有一条允许调用者的 ssh 规则。TSLink 只检测第一个条件并指出两者；它不会开启 Tailscale SSH，也不会修改 policy 文件。

三种结果都是 informational，永远不会改变 doctor 的 status 或退出码。

tslink access explain#

解释一个已注册服务如何被访问，包括 tailnet endpoint、--allow 行为和 Funnel 暴露。

tslink template list#

列出内置个人模板。

tslink template show#

显示一个内置模板定义。

tslink template apply#

应用内置模板。使用 --dry-run 可在不写入 registry 的情况下预览 plan。

配置

tslink config#

管理持久化在 ~/.config/tslink/config.json 中的全局 TSLink 设置。

子命令：

可用配置键：

# 设置 Headscale 控制服务器
tslink config set control-url https://headscale.example.com

# 查看当前值
tslink config get control-url

# 清除（恢复 Tailscale 默认）
tslink config set control-url ""

# 显示所有设置
tslink config list

tslink logs#

查看 TSLink 守护进程日志输出。默认读取 stderr 日志（tslink.err.log）的最后 50 行。

标志：

# 显示最后 50 行日志
tslink logs

# 显示最后 100 行
tslink logs --last 100

# 仅显示错误
tslink logs --level error

# 显示标准输出日志
tslink logs --source out

# JSON 输出
tslink logs --last 20 --json

系统

tslink install#

注册 TSLink 为开机自启动。

tslink install

• macOS：创建 LaunchAgent（~/Library/LaunchAgents/com.tslink.daemon.plist）
• Linux：创建 systemd 用户服务（~/.config/systemd/user/tslink.service）
• Windows：注册交互用户 Task Scheduler 任务，启动内建 supervisor 并恢复 daemon 崩溃。--startup 为明确选择的 fallback，无崩溃恢复。

在 macOS 上，gui/$(id -u) 只在该用户存在桌面（Aqua）会话时才存在。可用性取决于会话本身，而不是你是否通过 SSH 连接。首次安装会回退到 user/$(id -u)；升级时若某个曾经使用过的域无法检查，则拒绝执行，因为 TSLink 无法证明那个域是空的。该拒绝以 exit 1 返回，error.code 为 launchctl_domain_unavailable，其 data 给出不可用的域、完整的 --force 命令以及残留风险。

tslink uninstall#

移除自启动注册。

tslink uninstall

同样的域规则适用。当没有任何域确认任务已卸载、且至少有一个域无法检查时，uninstall 保留 plist 并以 exit 1 退出，使恢复句柄得以保存。--force 会照样移除它，并说明如何检查以及如何移除可能仍在加载的任务。

编程式访问

已发布 manifest 中的命令，除 stdio 的 tslink mcp 服务器外，都接受 --json，并向 stdout 写出一个带版本的信封，因此 owner 侧自动化就是同一套 CLI 加一个 flag。Cobra 的 help 和 completion 命令不在 manifest 中，只输出纯文本。MCP client 通过 tslink mcp 或远程 MCP 控制面执行同样的操作。

常见自动化命令：

# 列出本机已注册的服务
tslink list --json

# 添加服务
tslink add myapp --proxy localhost:3000 --json

# 删除服务
tslink remove myapp --json

# 查看状态
tslink status --json

# 运行只读诊断
tslink doctor --json

# 解释一个服务的本地访问模型
tslink access explain myapp --json

# 先预览、再应用内置模板
tslink template list --json
tslink template apply local-web --dry-run --json
tslink template apply local-web --yes --json

--json 只改变输出格式。tslink add --json 与人类路径使用同一套安全护栏：Funnel 服务必须传 --public，TCP 服务会拒绝 --allow，因为 TSLink 不会对原始 TCP 字节流应用 HTTP 身份检查。

每个 --json 响应都使用 JSON 输出格式 一节描述的带版本信封：命令载荷放在 data 下，结构化错误放在 error 下，command 记录产生该输出的命令。一次成功（在没有任何服务的机器上执行 tslink list --json）如下：

{"type": "tslink.result", "ok": true, "schema_version": 1, "command": "list", "code": 0, "data": {"schema_version": 1, "services": [], "count": 0}}

一次用法错误（tslink list --tailnet --verbose --json）如下：

{"type": "tslink.result", "ok": false, "schema_version": 1, "command": "list", "code": 2, "error": {"code": "usage_error", "message": "--tailnet conflicts with --verbose; --verbose filters this machine's registered services, while --tailnet reports tailnet devices", "next": ["tslink --help"]}}

MCP client 可以通过 tslink mcp（stdio）以及 tslink serve --mcp 启动的 tailnet-only 远程控制面执行同样的操作；参见 TSLink 作为 MCP 服务器。

tslink mcp#

在本地通过 stdio 启动一个 Model Context Protocol 服务器，让 MCP 客户端把 TSLink 当作工具来驱动，而不必解析 CLI 输出。它在 stdin/stdout 上使用按行分隔的 JSON-RPC 2.0，owner 会话暴露 44 个工具，精简角色更少：从 share、list、unshare、status，到 add、url、tags_*、access_explain、doctor、logs、invite_* 和 template_*。

tslink mcp

MCP 进程本身不会打开任何网络监听端口，也不需要 mcp.allow 条目；share 可能会启动独立的 TSLink daemon 和它请求的 tsnet 服务。协议帧走 stdout、诊断信息走 stderr，因此这里会拒绝 --json：stdout 已被协议帧独占。

tslink serve --mcp 在一个专用的 tailnet-only tsnet 节点上通过 HTTPS 提供依角色变化的工具集合（owner 为 44 个），供 tailnet 内其它机器上的 MCP client 使用。它默认关闭，且要求 config.json 中配置非空 owner mcp.allow 或明确 mcp.bindings。

客户端配置、完整的工具 schema、远程控制面和端到端示例，请看 TSLink 作为 MCP 服务器。

tslink manifest#

打印已安装二进制文件对自身的机器可读描述：每个命令、每个标志、退出码、错误码、凭据来源，以及导出的安全能力清单。这是 agent——以及本文档站点自己的 parity 检查——用来确认某个具体安装的构建实际支持什么，而不是相信文字描述的方式。

tslink manifest 对 tslink --help 隐藏（它是面向机器的命令，不是人类的操作步骤），但它和其它子命令一样可以直接运行：

tslink manifest              # 完整 manifest，缩进 JSON
tslink manifest --compact    # 仅命令、标志和稳定错误码
tslink manifest --json       # 完整 manifest，包在标准 --json envelope 里

标志：

本文档站点的 CLI parity 检查（pnpm parity:check）把已提交的 fixture 与这份 manifest 的形状逐项比对；该 fixture 由 TSLink 自己的 go run ./tools/gen-manifest 生成，不是手工维护的。

Roadmap / Experimental 命令和字段

关于 roadmap 命令和字段（middleware、Docker 集成、Admin REST API、自定义域名/ACME）的详情，请参阅实验性与路线图。

全局标志

tslink --help
tslink add --help
tslink status --json

退出码

所有命令返回语义化退出码，便于程序化错误处理：

JSON 输出格式

传递 --json 时，CLI 命令输出 JSON 信封；tslink mcp 是明确的例外：

{
  "type": "tslink.result",
  "ok": true,
  "schema_version": 1,
  "command": "status",
  "code": 0,
  "data": {
    "supervision": {
      "manager": "none",
      "installed": false,
      "autostart": false,
      "restart_on_exit": false,
      "detail": "No launchd ownership/autostart could be verified. Run: tslink install"
    },
    "daemon_running": false,
    "daemon_state": "absent",
    "daemon_pid": 0,
    "ownership_proof_available": true,
    "authenticated": false,
    "credential_stored": false,
    "credentials": {
      "api_key": {
        "present": false,
        "expiry_state": "none",
        "early_warning": {
          "state": "none",
          "source": ""
        }
      },
      "client_secret": {
        "present": false,
        "expiry_state": "none",
        "early_warning": {
          "state": "none",
          "source": ""
        }
      }
    },
    "credential_expiry_state": "none",
    "node_authorized": false,
    "authorized_service_count": 0,
    "auth_status": "not_authenticated",
    "service_count": 0,
    "services": [],
    "guest_links": [],
    "access_log": {
      "current": false,
      "enabled": true,
      "last_write": null,
      "drops": 0,
      "size_bytes": 0,
      "error": "access_log_not_started",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    "portal": {
      "enabled": false,
      "state": "disabled"
    },
    "alerts": {
      "notifier": "none",
      "events": []
    }
  }
}

错误时，error 字段是带稳定字符串 code 的结构化对象。下面是网关未运行时 tslink url nonexistent --json 的实际前提错误；即使名称不存在，也会先返回 exit 1 / daemon_not_running。网关运行后，对不存在服务的查询才会到达 exit 5 / not_found：

{
  "type": "tslink.result",
  "ok": false,
  "schema_version": 1,
  "command": "url",
  "code": 1,
  "error": {
    "code": "daemon_not_running",
    "message": "TSLink is not running; install and start its background service with 'tslink install'",
    "next": [
      "tslink install"
    ]
  }
}

应用与访问者

tslink apps#

通过 recipes 列出、发现和分享自托管应用，不安装或配置应用。

tslink apps list#

列出带版本的 recipe catalog 与应用侧配置建议。

tslink apps detect#

只读、有限的 loopback HTTP GET 指纹检测。部分结果返回 complete: false；匹配不能证明认证或健康。

tslink apps share#

默认预览，--yes 才应用，--dry-run 优先。保留已有名称；先核对应用登录、proxy trust、健康路径与主机端口。

tslink apps share jellyfin
tslink apps share jellyfin --yes

tslink people#

管理人员的私有 HTTP/文件访问。TCP 与公共 Funnel 无法按人限制。见人员分享。

tslink people add#

为新访问者授权，--apps 必填。首次授权收紧应用范围。--invite 创建逐应用邀请，--print-links 展示 bearer link。本地授权不需 token；创建邀请需用户自己的 API token。

tslink people add alice@example.com --apps photos --for 7d

tslink people list#

读取人员、授权、期限与撤销记录，不创建邀请。

tslink people update#

修改应用范围、期限或明确续做邀请。只改应用时保留已有期限，新增应用默认 24h；--for 应用于所有选定应用。查看 complete 与逐应用 state/code。未知 POST 需主人核对后 reconcile；替换邀请保留授权和期限。

tslink people remove#

先保存本地拒绝，再清理待接受邀请。没有 token 也能拒绝；远端清理可能未完成，已接受的网络分享可能保留。新 HTTP/文件请求被拒绝，已有流可继续。

访问流程与历史

tslink access log#

读取保留的历史与汇总，不调用远程 API、不创建文件/锁。见访问历史。

tslink access path <app> <prefix|full|off|inherit|true|false>#

设置单应用路径隐私。全局 off 优先，full 可能保存敏感应用路径，inherit 清除本地覆盖。

tslink extend <service>#

把一个人员授权（--person）或 Funnel（省略）设为当前时间加时长，始终返回 JSON。到期需 --regrant，撤销仍拒绝。见期限。

tslink guest#

管理单个 HTTP proxy 应用的浏览器 guest 授权，公网 Funnel 必须有访客 gate。

tslink guest create <app>#

--for 必填，启用 gate 时显式 --public。--print-link 前需私有应用在线，只展示一次 bearer 链接；拒绝 file/TCP 与已有开放 Funnel。见访客链接。

tslink guest list#

列出不含秘密的授权、期限和本地使用估计，不返回 bearer token。

tslink guest revoke <id>#

永久撤销该 ID，取消受跟踪的 guest 流；已经接受的有界请求可能完成。

tslink guest show <id>#

检查单个授权，不恢复链接或 PIN。

tslink mcp-audit#

Owner 读取有界 intent/completion receipt；缺 completion 表示结果未知，不保证审计完整。

tslink portal#

管理每台主机的私有 portal，不汇总多主机、不改变应用注册。

tslink portal disable#

只关闭 portal 监听，保留入网状态及 owner/admin 身份。

tslink portal enable#

--owner 必填，保存私有 portal 配置，由 daemon 应用。用 status --urls 获取准确运行 URL。远程 MCP 还需当前 portal owner；首次设置/恢复需本地进行。

tslink requests#

查看真人 tailnet 成员从 portal 发出的访问请求。见portal 与请求。

tslink requests approve <id>#

--for 必填，按主人选择的期限授权单应用；相同重试不续期。远程 owner/people-manager 还需当前 portal owner、应用/期限范围；精简角色要求人员已存在。

tslink requests deny <id>#

拒绝一个请求，相同重试返回原决定；远程调用有相同 portal-owner 检查。

tslink requests list#

读取持久 inbox，保留维护可能写入；备注是不可信数据。

普通命令继承 --json；extend 始终返回 JSON。MCP stdout 专用于协议 frames。