lnctl CLI Usage Guide

This guide covers common lnctl commands, global flags, output behavior, and typical workflows.

1. Quick Help

Show version:

2. Global Flags

lnctl supports these global flags (available on all subcommands):

--output: output format (json / yaml / table); if the value is invalid, or the current command does not support that format, the CLI resets it to the default json

--timeout: request timeout in seconds, range 10-300, default 30; if the value is invalid or out of range, the CLI resets it to the default 30

--version: print version information

3. Command Overview

Top-level resource commands:

vps

firewall

image

ssh-key

region

package

task

api-key

upgrade

4. Common Command Examples

4.1 VPS Operations

Show instance detail:

List instances (default table):

Create instance (--ssh-key-uuid or --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

Handling values that contain special characters

If a parameter value contains special characters, such as a comma, space, or other symbol in a password, prefer the --option='value' form.

Recommended:

use = between the option name and the value

wrap the value in single quotes

Example:

Lifecycle operations:

Reset password:

If a password or other parameter value contains special characters, see lnctl vps create in "Handling values that contain special characters".

Reset OS (--ssh-key-uuid or --password):

If a parameter value contains special characters, see lnctl vps create in "Handling values that contain special characters".

4.2 Read-Only Resource Queries

Firewall:

Image (default table includes REGION column):

SSH key:

Region:

Package:

4.3 Async Task Query

4.4 Manage local api-keys

Show API key help:

Add a new API key:

List saved local API keys:

Switch the current API key:

Delete an API key you no longer use:

4.5 Upgrade lnctl

Check for the latest version and upgrade within the current release channel:

Skip confirmation for automation:

Reinstall the latest version even if current version is already latest:

Notes:

lnctl upgrade does not require a LightNode API key.

The upgrade flow downloads the matching package for current OS/ARCH, verifies SHA256, backs up the current binary, replaces it, and runs lnctl --version after replacement.

For transient network errors during latest version, checksums, or artifact downloads, the CLI performs short retries before returning a readable error.

For HTTP non-2xx responses, the CLI prints URL, HTTP status, and an optional short response snippet instead of dumping a full HTML error page.

Linux/macOS keeps a same-directory backup as lnctl.bak.

Windows starts a helper cmd process in the current terminal for the final replacement, keeps a same-directory backup as lnctl.exe.bak, and prints the final success/failure result back to the current terminal.

The Windows helper uses a separate staging directory for the new binary, retries replacement automatically, and removes the staging directory after success.

5. Output Behavior

list commands default to table.

Non-list commands default to json.

If --output is not passed explicitly, list commands still default to table (current fixed behavior).

If --output is invalid, the CLI prints Invalid output value, reset to default: json and resets it to json.

If --output table is passed to a command that does not support table, the CLI also prints Invalid output value, reset to default: json and resets it to json.

If --timeout is invalid, the CLI prints Invalid timeout value, reset to default: 30 and resets it to 30.

Examples:

6. Authentication

lnctl now keeps only one authentication mechanism: local encrypted API key storage.

Other runtime authentication entry points are no longer supported, and local config files are no longer used for authentication.

The default local files are now:

~/.lnctl/api-key.key

~/.lnctl/api-keys.enc

6.1 First authenticated command

If you run an authenticated command for the first time, for example:

and no current API key exists locally, the CLI prompts immediately:

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.

After the save succeeds, the current command continues automatically. Later commands reuse the current API key.

6.2 Manage local API keys manually

You can also manage local API keys at any time with:

This root entry shows help and points to these subcommands:

lnctl api-key add

prompts for a local API key name and API key

asks for confirmation before overwriting an existing name

if no current API key exists yet, the new entry becomes current automatically

if a current API key already exists, the new entry is saved without switching current

lnctl api-key add <name>

uses the given name directly

prompts only for the API key, not the name again

still asks for confirmation before overwriting an existing name

follows the same current-selection rule as lnctl api-key add

lnctl api-key list

prints a table of saved names and the current entry

lnctl api-key switch

switches the current API key interactively

lnctl api-key switch <name>

switches directly to the given name

does not show the interactive list

prints a friendly message if the target is already current

lnctl api-key delete

deletes an API key interactively

asks for confirmation before deletion

lnctl api-key delete <name>

deletes the given name directly

still asks for confirmation

lnctl api-key delete <name> --force

skips the confirmation step

does not support the -f shorthand

--force skips confirmation only; it does not ignore not-found errors

When the deleted entry is the current API key, the CLI automatically resolves the next current value:

no API keys left: clear the current value

one API key left: switch to the remaining entry automatically

multiple API keys left:

interactive deletion or non-force named deletion prompts for the next current API key

force deletion picks the first name from a stable order automatically

6.3 What is a local API key name

The local api-key name is the name you use on your machine to distinguish different API keys.

Examples:

dev

prod

test

6.4 How authenticated commands read API keys

Before running an authenticated command, you can check the current API key with:

If no usable API key is configured locally, the CLI automatically enters the interactive setup flow.

7. Troubleshooting

7.1 Missing API key error

Check in order:

whether the current terminal is interactive

whether lnctl api-key add has already been run

whether ~/.lnctl/api-key.key and ~/.lnctl/api-keys.enc exist

whether a current API key is set locally

7.2 Action command returns async task

For create/delete/start/stop/restart/reset operations, continue with:

7.3 Output too long

Use default table first. For full payload, switch to:

7.4 Intermittent `lnctl upgrade` network failures

If you see EOF, connection reset, or timeout-related download errors:

retry lnctl upgrade --yes once first

if a local proxy is configured, verify the proxy path is healthy

focus on the URL and Network error fields in the message

The CLI now performs short retries before printing the final network error.

7.5 Windows upgrade keeps using the current terminal

This is expected behavior.

Windows cannot replace the currently running lnctl.exe in-place

lnctl upgrade launches a helper cmd process that continues the final replacement in the current terminal

Keep the current terminal open until the final Upgrade completed. or Upgrade failed: ... result is printed

If you want an extra confirmation step, run lnctl --version

1. Quick Help#

2. Global Flags#

3. Command Overview#

4. Common Command Examples#

4.1 VPS Operations#

Handling values that contain special characters#

4.2 Read-Only Resource Queries#

4.3 Async Task Query#

4.4 Manage local api-keys#

4.5 Upgrade lnctl#

5. Output Behavior#

6. Authentication#

6.1 First authenticated command#

6.2 Manage local API keys manually#

6.3 What is a local API key name#

6.4 How authenticated commands read API keys#

7. Troubleshooting#

7.1 Missing API key error#

7.2 Action command returns async task#

7.3 Output too long#

7.4 Intermittent lnctl upgrade network failures#

7.5 Windows upgrade keeps using the current terminal#