lnctl CLI 使用文档

本文档用于说明 lnctl 的常用命令、全局参数、输出规则和典型操作流程。

1. 快速查看帮助

查看版本信息：

2. 全局参数

lnctl 支持以下全局参数（所有子命令可用）：

--output：输出格式，支持 json / yaml / table；如果值非法，或当前命令不支持该输出格式，会自动回退到默认 json

--timeout：请求超时时间，单位秒，范围 10-300，默认值 30；如果值非法或超出范围，会自动回退到默认 30

--version：输出版本信息

3. 命令总览

一级资源命令：

vps

firewall

image

ssh-key

region

package

task

api-key

upgrade

4. 常用命令示例

4.1 VPS 管理

查询详情：

列表查询（默认 table）：

创建实例（--password 与 --ssh-key-uuid 二选一）：

密码规则如下（reset-password 和 reset-os 使用 --password 时同样适用）：

Password rules:

8-30 characters

Must include uppercase letters, lowercase letters, and numbers

Must include at least one of the following special characters: ()`~!@#$*-+={}[]:;,.?/

主机名称规则如下：

Instance name rules:

Maximum length: 64 characters

Only letters (A-Z, a-z), numbers (0-9), and hyphens (-) are allowed

含特殊字符的参数值处理办法

如果参数值包含特殊字符，例如密码中包含逗号、空格或其他特殊符号，推荐使用 --参数名='参数值' 的形式。

建议：

使用 = 连接参数名和值

使用单引号包围参数值

例如：

停止实例：

启动实例：

重启实例：

重置密码：

新密码需符合上文 create 中的密码规则；如需跳过确认，可加 --force。

如果密码或其他参数值包含特殊字符，请参考 lnctl vps create 章节中的“含特殊字符的参数值处理办法”。

重装系统（--password 与 --ssh-key-uuid 二选一）：

使用 --password 时，密码需符合上文 create 中的密码规则；如需跳过确认，可加 --force。

如果参数值包含特殊字符，请参考 lnctl vps create 章节中的“含特殊字符的参数值处理办法”。

删除实例：

如需跳过确认，可加 --force。

4.2 只读资源查询

安全组：

镜像（默认 table，包含 REGION 列）：

SSH Key：

地域：

套餐：

4.3 异步任务查询

4.4 本地 api-key 管理

查看 api-key 相关帮助：

添加新的 api-key：

查看本地已保存的 api-key：

切换当前默认 api-key：

删除不再使用的 api-key：

4.5 升级 lnctl

检查并升级到当前 release channel 的 latest 版本：

跳过确认，适合脚本或自动化环境：

即使当前已经是 latest，也重新下载并安装：

说明：

lnctl upgrade 不需要 LightNode API key。

升级过程会下载对应 OS/ARCH 的安装包，校验 SHA256，替换前备份当前二进制，替换后执行 lnctl --version 验证。

对 latest version、checksums、artifact 下载阶段的瞬时网络错误，CLI 会自动做短重试；重试耗尽后再输出可读错误信息。

HTTP 非 2xx 时会优先展示 URL、HTTP status 和必要的短响应摘要，不再把整段 HTML 错页直接打印到终端。

Linux/macOS 备份文件为同目录 lnctl.bak。

Windows 会在当前终端启动 helper cmd 进程继续完成延迟替换，备份文件为同目录 lnctl.exe.bak，最终成功/失败结果也会回到当前终端输出。

Windows helper 会先从独立 staging 临时目录读取新 lnctl.exe，自动重试替换，成功后清理 staging 目录。

5. 输出规则

list 类命令默认输出 table。

非 list 命令默认输出 json。

list 类命令如果没有显式传 --output，仍会默认输出 table（这是当前 CLI 的固定行为）。

如果显式传入非法 --output，CLI 会提示 Invalid output value, reset to default: json，并自动回退到 json。

如果在当前命令不支持 table 的场景下显式传 --output table，CLI 也会提示 Invalid output value, reset to default: json，并自动回退到 json。

如果显式传入非法 --timeout，CLI 会提示 Invalid timeout value, reset to default: 30，并自动回退到 30。

需要完整结构时可显式指定：

6. 认证说明

lnctl 现在只保留一种认证方式：本地加密存储 api-key。

不再支持其他运行期认证入口，也不再使用本地配置文件承载认证信息。

当前默认使用以下本地文件：

~/.lnctl/api-key.key

~/.lnctl/api-keys.enc

6.1 首次直接执行业务命令

如果你第一次执行需要认证的命令，例如：

当本地还没有默认 api-key 时，CLI 会直接进入交互流程：

Enter local api-key name (local label only, not sent to server): dev
Enter api-key: ********
Saved api-key "dev" and set it as current.

保存成功后，当前命令会继续执行；后续命令会自动读取当前默认 api-key。

6.2 主动管理本地 api-key

你也可以随时主动执行：

该入口只展示帮助，并引导你使用以下子命令：

lnctl api-key add

交互输入 local api-key name 和 api-key

如果名称已存在，更新前需要确认

如果当前还没有默认 api-key，新保存的 api-key 会自动成为当前默认值

如果当前已经有默认 api-key，只保存，不自动切换当前默认值

lnctl api-key add <name>

直接使用指定名称

只交互输入 api-key，不再重复询问名称

如果名称已存在，更新前仍需要确认

默认值处理规则与 lnctl api-key add 相同

lnctl api-key list

以表格展示本地 api-key 名称和当前默认项

lnctl api-key switch

交互式切换当前默认 api-key

lnctl api-key switch <name>

直接切换到指定名称

不展示交互列表

如果目标已经是当前默认值，会直接提示

lnctl api-key delete

交互式删除 api-key

删除前需要确认

lnctl api-key delete <name>

直接删除指定名称

删除前仍需要确认

lnctl api-key delete <name> --force

跳过确认直接删除

不支持 -f 简写

--force 只跳过确认，不会忽略不存在错误

删除当前默认 api-key 后，CLI 会自动处理新的当前默认 api-key：

没有剩余 api-key：清空当前默认值

只剩一个 api-key：自动切换到剩余项

剩余多个 api-key：

交互删除或非 force 指定删除时，提示你选择新的当前默认 api-key

--force 删除时，自动选择稳定顺序中的第一个名称

6.3 local api-key name 是什么

local api-key name 就是你本地用来区分不同 api-key 的名称。

例如：

dev

prod

test

6.4 业务命令如何读取 api-key

执行业务命令前，可以先用下面的命令确认当前默认 api-key：

如果本地还没有可用 api-key，CLI 会自动进入交互配置流程。

7. 常见排查

7.1 提示 api-key 缺失

优先检查：

当前终端是否可交互

是否已经执行过 lnctl api-key add

~/.lnctl/api-key.key 与 ~/.lnctl/api-keys.enc 是否存在

本地是否已经设置当前默认 api-key

7.2 变更命令返回异步任务

创建、删除、开关机、重装等命令可能先返回异步任务，请继续执行：

7.3 输出太长不易读

优先使用默认 table；需要完整字段时再切换到：

7.4 `lnctl upgrade` 偶发网络失败

如果看到 EOF、connection reset、timeout 之类的下载错误：

先直接重试一次 lnctl upgrade --yes

如本机配置了代理，优先确认代理可用性

重点关注错误输出中的 URL 和 Network error 字段

CLI 当前会先做短重试，再输出收敛后的网络错误提示。

7.5 Windows 升级会继续占用当前终端

这是预期行为。

Windows 不能在运行中的 lnctl.exe 进程内直接覆盖自己

lnctl upgrade 会启动 helper cmd 进程，在当前终端继续完成最终替换

请保持当前终端打开，等待 Upgrade completed. 或 Upgrade failed: ... 的最终结果输出

如需再次确认版本，可额外执行 lnctl --version

1. 快速查看帮助#

2. 全局参数#

3. 命令总览#

4. 常用命令示例#

4.1 VPS 管理#

含特殊字符的参数值处理办法#

4.2 只读资源查询#

4.3 异步任务查询#

4.4 本地 api-key 管理#

4.5 升级 lnctl#

5. 输出规则#

6. 认证说明#

6.1 首次直接执行业务命令#

6.2 主动管理本地 api-key#

6.3 local api-key name 是什么#

6.4 业务命令如何读取 api-key#

7. 常见排查#

7.1 提示 api-key 缺失#

7.2 变更命令返回异步任务#

7.3 输出太长不易读#

7.4 lnctl upgrade 偶发网络失败#

7.5 Windows 升级会继续占用当前终端#