# CLI 参考 `sqctl` 是你在终端里操作 SecurQbit 的方式。它通过本地套接字与后台服务通信；它不保存任何凭据，自身也不需要权限。如果还没安装，请先看[桌面与路由器设置](/cli-installation)。 每条命令都接受 `--json`，它会打印原始文档而不是排版后的输出。那才是应当拿来写脚本的接口 — 给人看的排版随时可能改动。 ## 一览 ```text sqctl status VPN 是否开启，以及以谁的身份 sqctl login 在浏览器中批准链接以登录 sqctl logout sqctl locations 当前套餐可用的国家 sqctl connect [COUNTRY] [--fastest] sqctl disconnect sqctl set 显示偏好设置 sqctl set country DE|any sqctl set autoconnect on|off sqctl set updates on|off sqctl update [--check] [--yes] 安装最新版本 ``` ## sqctl status 显示你是否受保护，以及以谁的身份。 ```text $ sqctl status ● Connected Germany Connected for 12m 40s Transferred ↓ 148 MB ↑ 22 MB Account Alice alice@example.com Plan Monthly Renews 1 September 2026 ``` 它刻意不显示隧道是怎么建立的 — 没有服务器地址，也没有会话标识。那些你无法据以行动，尤其是服务器地址，不该在你求助时随截图泄露出去。 如果服务没在运行，`sqctl` 会说明，并打印在*这台*机器上启动它的命令，无论它用的是哪种 init 系统。 ## sqctl login 通过在浏览器中批准，让这台电脑登录。 ```text $ sqctl login Open this link to approve the sign-in: https://accounts.securqbit.com/device?code=BCDF-GHJK Check the page shows this code: B C D F - G H J K Waiting for approval — expires in 10 minutes, Ctrl-C to cancel ``` 打开链接 —`sqctl` 会尝试替你打开，`--no-browser` 可阻止它这么做 — 若尚未登录则先登录，**核对页面上的验证码与终端里的一致**，然后批准。终端里永远不需要回填任何东西。 这一次核对，就是整个流程的全部安全性所在。 > **只批准你自己发起的请求。** 如果有人给你发来这样的链接而你批准了，你就把*他的*电脑登进了*你的*账号。页面上显示的验证码和机器名，正是让你分辨这一点的依据。 登录需要一个已经存在的账号。请在 [iOS 或 Android 应用](/installation)中创建 — 包括[访客账号](/anonymous-accounts)，它用恢复码登录 accounts.securqbit.com，并像其他账号一样在那里批准。 ## sqctl logout 关闭 VPN 并注销这台电脑。隧道会先断开，这是刻意的：让隧道挂在刚被吊销的凭据上，会把你的流量丢在服务器即将清除的会话里。 [访客账号](/anonymous-accounts)会先要求确认，因为没有恢复码你将无法再登录。`--force` 可跳过询问。 ## sqctl connect ```bash sqctl connect # 你保存的偏好 sqctl connect DE # 显示为德国 sqctl connect --fastest # 让 SecurQbit 决定 ``` 国家是两位字母代码 — 运行 `sqctl locations` 查看你的套餐允许哪些。连接需要几秒；终端会跟随实际状态的变化，而不是一言不发。 > **试用版无法选择国家。** 试用套餐请用 `--fastest`。指定国家会返回一个错误，说明需要付费套餐，而不是悄悄把你连到别处。参见[账号与计费](/account-billing)。 ## sqctl disconnect 断开隧道，并把你的路由和 DNS 恢复原状。 断开同时也是在告诉 SecurQbit *停下*。如果隧道自己断了，服务会持续尝试把它恢复 — 这正是你希望笔记本从睡眠中醒来、或路由器上行抖动之后发生的事。只有 `sqctl disconnect`、退出登录或停止服务，才会取消这个意图。 ## sqctl locations 按名称列出你的套餐可用的国家。 ```text $ sqctl locations DE Germany FR France NL Netherlands SG Singapore US United States ``` ## sqctl set 显示或修改你的偏好。一共三项，而这三项确实该由你来决定。 ```bash sqctl set # 显示这三项 sqctl set country DE # 默认使用德国 sqctl set country any # 默认使用最快的 sqctl set autoconnect on # 机器一启动就连接 sqctl set updates off # 不再检查新版本 ``` ```text $ sqctl set Location Germany (DE) Auto-connect on Updates on ``` 隧道的其他一切 — 怎么建立、用什么 DNS、如何重试 — 都已替你决定，且不通过 CLI 暴露。把这些选项抛出来，并不会让一个 VPN 变得更好。 `updates` 之所以是一项设置而不是固定行为，是因为这项检查是对 SecurQbit CDN 的周期性访问，而运行 VPN 的人有权拒绝它。 ## sqctl update 安装最新版本。 ```bash sqctl update # 询问后安装并重启 sqctl update --check # 只说明有没有新版本 sqctl update --yes # 不询问 ``` ```text $ sqctl update ! Update available Installed v1.0.0 Latest v1.1.0 SecurQbit restarts to finish, so the VPN disconnects for a moment. Install it now? [y/N] ``` 在替换任何文件之前，下载内容都会与已发布的校验和比对，随后服务在新版本上重启。`sqctl` 会等它回来并读取版本号，所以告诉你的是实际正在运行的版本，而不是写进磁盘的版本。 SecurQbit 也会每天自行检查一次，并且只是告知你 — 在 `sqctl status` 下的一行： ```text Update v1.1.0 available — run: sqctl update ``` 它从不自行安装。完成更新意味着重启，而重启会断开正在使用的隧道；不打招呼就这么做，比让人落后一个版本更糟。 如果 SecurQbit 是由你的发行版包管理器安装的，`sqctl update` 会在下载任何东西之前拒绝，并提示你用当初的安装方式去更新。 ## 编写脚本 任意命令加上 `--json`，都会打印协议原文： ```bash $ sqctl status --json | jq '.state, .country' "connected" "DE" ``` ```bash # 连接并确认确实生效 sqctl connect --fastest --json > /dev/null test "$(sqctl status --json | jq -r .state)" = connected ``` 退出码：`0` 成功，`1` 命令失败，`2` 无法连上 SecurQbit 服务。 ## 出问题的时候 `sqctl` 会把失败翻译成你能据以行动的说法，并把内部细节挡在外面。当你确实需要那些细节 — 比如提交问题报告 — 有一个隐藏的诊断命令： ```bash sqctl debug # 版本、各类文件位置、是哪个套接字应答、 # 隧道引擎，以及最后一次的原始错误 sqctl debug probe DE # 在“不连接”的前提下端到端测试某个服务器 ``` `sqctl debug probe` 最为实用。它对着真实服务器启动代理，通过它发一次请求，并报告对端看到的地址 — 但它不创建隧道设备，也不改动任何路由，所以即便链路不通，它也能告诉你结果而不会让你断网。 报告问题时请附上 `sqctl debug` 的输出。参见[故障排除](/troubleshooting)。 ## 下一步 - [桌面与路由器设置](/cli-installation) — 安装、更新与卸载。 - [连接到服务器](/connecting) — 服务器选择是怎么工作的。 - [绕过防火墙与流量混淆](/firewall-bypass) — 在受限网络中。