Codestin Search App

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

1. Quick Start

Show global help:

Show help for a specific resource command:

Show version information:

2. Global Flags

lnctl supports the following global flags. They are available on all subcommands.

Flag	Description
`--output`	Output format. Supported values: `json` / `yaml` / `table`
`--timeout`	Request timeout in seconds. Range: `10-300`. Default: `30`
`--version`	Print version information

Notes:

If the value of --output is invalid, the CLI resets it to the default json.

If the current command does not support the specified output format, the CLI also resets it to the default json.

If the value of --timeout is invalid or out of range, the CLI resets it to the default 30.

Examples:

3. Command Overview

lnctl currently supports the following top-level resource commands:

Command	Description
`vps`	VPS instance management
`firewall`	Firewall query
`image`	Image query
`ssh-key`	SSH Key query
`region`	Region query
`package`	Package query
`task`	Async task query
`api-key`	Local API Key management
`upgrade`	Upgrade `lnctl`

4. Authentication

lnctl uses locally saved API Keys for authentication by default.

Default local file paths:

~/.lnctl/api-key.key
~/.lnctl/api-keys.enc

4.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 enters the interactive setup flow automatically:

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 API Key is saved successfully, the current command continues automatically.

Later commands reuse the current default API Key automatically.

4.2 What is a local api-key name

local api-key name is a local label used to distinguish different API Keys on your machine. It is not sent to the server.

Common examples:

dev
test
prod

4.3 Manage local API Keys

Show API Key management help:

Add an API Key:

List saved local API Keys:

Switch the current default API Key:

Delete an API Key:

Notes:

lnctl api-key add prompts for both local api-key name and api-key.

lnctl api-key add <name> uses the specified name and only prompts for api-key.

If the name already exists, confirmation is required before overwriting it.

If no current API Key exists, the newly saved API Key becomes the current default automatically.

If a current API Key already exists, the newly saved API Key is only saved and does not become the current default automatically.

lnctl api-key delete <name> --force skips the delete confirmation.

--force does not support the -f shorthand.

--force only skips confirmation. It does not ignore API Key not-found errors.

4.4 Default API Key handling after deletion

If the deleted API Key is the current default API Key, the CLI automatically resolves the next current default API Key:

Remaining API Keys	Behavior
0	Clear the current default value
1	Automatically switch to the remaining API Key
Multiple	Depends on the deletion mode

When multiple API Keys remain:

Interactive deletion or non---force named deletion prompts you to select the next default API Key.

--force deletion automatically selects the first name from a stable order.

5. Parameter Values and Special Characters

If a parameter value contains special characters, such as a comma, space, or other symbols in a password, the following format is recommended:

Recommendations:

Use = between the option name and the value.

Wrap the value in single quotes.

Example:

This rule also applies to commands that accept passwords, such as reset-password and reset-os.

6. VPS Management

6.1 Show instance detail

6.2 List instances

vps list defaults to table output.

List instances with pagination:

6.3 Create an instance

When creating a VPS, use either --password or --ssh-key-uuid.

Create with password:

Create with SSH Key:

6.4 Password rules

When using --password in create, reset-password, or reset-os, the password must meet the following rules:

Length: 8-30 characters.

Must include an uppercase letter: [A-Z].

Must include a lowercase letter: [a-z].

Must include a number: [0-9].

Must include at least one of the following special characters:

()`~!@#$*-+={}[]:;,.?/

6.5 Instance name rules

The instance name must meet the following rules:

Maximum length: 64 characters.

Only the following characters are allowed:

Uppercase letters

Lowercase letters

Numbers

Hyphen -

6.6 Stop an instance

6.7 Start an instance

6.8 Restart an instance

6.9 Reset password

Skip confirmation:

Notes:

The new password must meet the password rules described above.

If the password contains special characters, use --password='<new-password>'.

6.10 Reset OS

When resetting the OS, use either --password or --ssh-key-uuid.

Reset OS with password:

Reset OS with SSH Key:

Skip confirmation:

Notes:

When using --password, the password must meet the password rules described above.

If the password contains special characters, use --password='<password>'.

6.11 Delete an instance

Skip confirmation:

7. Read-Only Resource Queries

7.1 List firewalls

7.2 List images

image list defaults to table output, and the table includes the REGION column.

For the full structure:

7.3 List SSH Keys

7.4 List regions

7.5 List packages

8. Async Task Query

Action commands such as create, delete, start, stop, restart, and reset OS may return an async task.

Query the task status with:

You can also pass the task ID directly:

9. Upgrade lnctl

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

Skip confirmation. This is useful for scripts or automation environments:

Re-download and reinstall the latest version even if the current version is already the latest:

Notes:

lnctl upgrade does not require a LightNode API Key.

Linux and macOS keep a same-directory backup file: lnctl.bak.

Windows starts a helper cmd process in the current terminal to complete the delayed replacement.

The Windows backup file is stored in the same directory as lnctl.exe.bak.

The final success or failure result of a Windows upgrade is printed back to the current terminal.

10. Output Behavior

10.1 Default output format

Command Type	Default Output
`list` commands	`table`
Non-`list` commands	`json`

Notes:

list commands default to table when --output is not specified explicitly.

Non-list commands default to json.

When you need the full structure, explicitly use json or yaml.

Examples:

10.2 Invalid output handling

If an invalid --output value is provided, the CLI prints:

Invalid output value, reset to default: json

and resets the output format to json.

Example:

10.3 Unsupported table output

If the current command does not support table, but --output table is specified explicitly, the CLI prints:

Invalid output value, reset to default: json

and resets the output format to json.

10.4 Invalid timeout handling

If an invalid --timeout value is provided, the CLI prints:

Invalid timeout value, reset to default: 30

and resets the timeout to 30.

11. Common Workflows

11.1 First-time use

If no API Key exists locally, the CLI enters the interactive setup flow automatically.

After configuration, check the current API Key:

11.2 Create a VPS

Query regions, packages, and images first:

Then create a VPS:

If the command returns an async task, continue querying the task status:

11.3 Reset a VPS OS

Skip confirmation:

11.4 Delete a VPS

Skip confirmation:

12. Troubleshooting

12.1 Missing API Key error

Check the following items first:

Whether the current terminal is interactive.

Whether lnctl api-key add has already been run.

Whether ~/.lnctl/api-key.key exists.

Whether ~/.lnctl/api-keys.enc exists.

Whether a current default API Key is set locally.

You can check with:

12.2 Action command returns an async task

Create, delete, start, stop, restart, and reset OS commands may return an async task first.

Continue querying the task status:

12.3 Output is too long

For list commands, use the default table output first.

If you need all fields, switch to:

or:

Examples:

12.4 Intermittent `lnctl upgrade` network failures

If you see download errors such as:

EOF
connection reset
timeout

Try the following steps in order:

Retry once directly:

If a local proxy is configured, verify that the proxy is available.

Pay attention to the URL and Network error fields in the error output.

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

12.5 Windows upgrade keeps using the current terminal

This is expected behavior.

Reason:

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

lnctl upgrade starts a helper cmd process and continues the final replacement in the current terminal.

What to do:

Keep the current terminal open.

Wait for the final output:

Upgrade completed.

or:

Upgrade failed: ...

After the upgrade is complete, confirm the version again:

lnctl CLI Usage Guide

1. Quick Start#

2. Global Flags#

3. Command Overview#

4. Authentication#

4.1 First authenticated command#

4.2 What is a local api-key name#

4.3 Manage local API Keys#

4.4 Default API Key handling after deletion#

5. Parameter Values and Special Characters#

6. VPS Management#

6.1 Show instance detail#

6.2 List instances#

6.3 Create an instance#

6.4 Password rules#

6.5 Instance name rules#

6.6 Stop an instance#

6.7 Start an instance#

6.8 Restart an instance#

6.9 Reset password#

6.10 Reset OS#

6.11 Delete an instance#

7. Read-Only Resource Queries#

7.1 List firewalls#

7.2 List images#

7.3 List SSH Keys#

7.4 List regions#

7.5 List packages#

8. Async Task Query#

9. Upgrade lnctl#

10. Output Behavior#

10.1 Default output format#

10.2 Invalid output handling#

10.3 Unsupported table output#

10.4 Invalid timeout handling#

11. Common Workflows#

11.1 First-time use#

11.2 Create a VPS#

11.3 Reset a VPS OS#

11.4 Delete a VPS#

12. Troubleshooting#

12.1 Missing API Key error#

12.2 Action command returns an async task#

12.3 Output is too long#

12.4 Intermittent lnctl upgrade network failures#

12.5 Windows upgrade keeps using the current terminal#

1. Quick Start

2. Global Flags

3. Command Overview

4. Authentication

4.1 First authenticated command

4.2 What is a local api-key name

4.3 Manage local API Keys

4.4 Default API Key handling after deletion

5. Parameter Values and Special Characters

6. VPS Management

6.1 Show instance detail

6.2 List instances

6.3 Create an instance

6.4 Password rules

6.5 Instance name rules

6.6 Stop an instance

6.7 Start an instance

6.8 Restart an instance

6.9 Reset password

6.10 Reset OS

6.11 Delete an instance

7. Read-Only Resource Queries

7.1 List firewalls

7.2 List images

7.3 List SSH Keys

7.4 List regions

7.5 List packages

8. Async Task Query

9. Upgrade lnctl

10. Output Behavior

10.1 Default output format

10.2 Invalid output handling

10.3 Unsupported table output

10.4 Invalid timeout handling

11. Common Workflows

11.1 First-time use

11.2 Create a VPS

11.3 Reset a VPS OS

11.4 Delete a VPS

12. Troubleshooting

12.1 Missing API Key error

12.2 Action command returns an async task

12.3 Output is too long

12.4 Intermittent `lnctl upgrade` network failures

12.5 Windows upgrade keeps using the current terminal