cli/docs/CLI_COMMANDS_DOCUMENTATION.md

Lux CLI Commands Documentation

The Lux CLI v2 is a unified toolchain for creating and managing sovereign L1s, based rollups (L2s), and app-specific chains (L3s). This document provides comprehensive documentation for all available commands.

Table of Contents

1. Overview
2. Global Flags
3. L1 Commands
4. L2 Commands
5. L3 Commands
6. Network Commands
7. Node Commands
8. Key Commands
9. Transaction Commands
10. Configuration Commands
11. Update Commands
12. Migration Commands

Overview

The Lux CLI supports multiple blockchain architectures:

• L1: Sovereign chains with independent validation
• L2: Based rollups or OP Stack compatible
• L3: App-specific chains on L2s

Features

• EIP-4844 blob support
• Pre-confirmations (<100ms acknowledgment)
• IBC/Teleport cross-chain messaging
• Corona post-quantum signatures

Global Flags

These flags are available for all commands:

--config <file>        # Config file (default: $HOME/.lux/cli.json)
--log-level <level>    # Log level for the application (default: ERROR)
--skip-update-check    # Skip check for new versions

L1 Commands

Manage sovereign L1 blockchains with their own validator sets, tokenomics, and consensus mechanisms.

lux l1 create

Create a new L1 blockchain configuration.

lux l1 create [l1Name] [flags]

Flags:

• --proof-of-authority: Use Proof of Authority validator management
• --proof-of-stake: Use Proof of Stake validator management
• --evm-chain-id <uint>: EVM chain ID for the L1
• --token-name <string>: Native token name
• --token-symbol <string>: Native token symbol
• -f, --force: Overwrite existing configuration

Examples:

# Create PoA L1 interactively
lux l1 create myL1

# Create PoS L1 with specific parameters
lux l1 create myL1 --proof-of-stake --evm-chain-id 96369 --token-name "MyToken" --token-symbol "MTK"

lux l1 deploy

Deploy a sovereign L1 blockchain to local, testnet, or mainnet.

lux l1 deploy [l1Name] [flags]

Flags:

• -l, --local: Deploy to local network
• -t, --testnet: Deploy to testnet
• -m, --mainnet: Deploy to mainnet
• --use-existing: Use existing blockchain data
• --protocol <string>: Protocol to use (lux, lux-compat) (default: "lux")

Examples:

# Deploy to local network
lux l1 deploy myL1 --local

# Deploy to testnet with existing data
lux l1 deploy myL1 --testnet --use-existing

lux l1 list

List all configured L1 blockchains.

lux l1 list

lux l1 describe

Show detailed information about an L1 blockchain.

lux l1 describe [l1Name]

lux l1 validator

Manage validators for an L1 blockchain.

lux l1 validator [subcommand] [l1Name] [flags]

Subcommands:

• add: Add a validator to the L1
• remove: Remove a validator from the L1
• list: List all validators

lux l1 upgrade

Upgrade an L1 blockchain configuration.

lux l1 upgrade [l1Name] [flags]

lux l1 import

Import an existing L1 configuration.

lux l1 import [l1Name] [flags]

lux l1 migrate

Migrate L1 data between networks.

lux l1 migrate [l1Name] [flags]

Chain Commands

Create and manage chains. The chain command is the canonical entry point; no aliases exist.

lux chain create

Create a new chain configuration.

lux chain create [chainName] [flags]
lux chain create [chainName] [flags]  # alias

Flags:

• --evm: Use the Lux EVM as the base template
• --custom: Use a custom VM template
• --genesis <file>: File path of genesis to use
• --vm <file>: File path of custom VM to use
• --vm-version <string>: Version of VM template to use
• --latest: Use latest VM version
• -f, --force: Overwrite existing configuration
• --sequencer <string>: Sequencer for the L2 (lux, ethereum, lux, op, external)
• --enable-preconfirm: Enable pre-confirmations for fast UX

Sequencing Models:

• lux: Based rollup, 100ms blocks, lowest cost
• ethereum: Based rollup, 12s blocks, highest security
• lux: Based rollup, 2s blocks, fast finality
• op: OP Stack compatible for Optimism ecosystem
• external: Traditional centralized sequencer

Examples:

# Create L2 with interactive wizard
lux chain create myL2

# Create L2 with Ethereum-based sequencing
lux chain create myL2 --evm --sequencer ethereum --enable-preconfirm

# Create L2 with custom genesis
lux chain create myL2 --genesis ./genesis.json --force

lux chain deploy

Deploy an L2 chain.

lux chain deploy [chainName] [flags]

Similar flags to L1 deploy

lux chain list

List all configured L2 chains.

lux chain list

lux chain describe

Show detailed information about an L2 chain.

lux chain describe [chainName]

lux l2 join

Join a validator to an L2 chain.

lux l2 join [chainName] [flags]

lux l2 addValidator

Add a validator to an L2 chain.

lux l2 addValidator [chainName] [flags]

lux l2 removeValidator

Remove a validator from an L2 chain.

lux l2 removeValidator [chainName] [flags]

lux l2 export

Export L2 chain configuration.

lux l2 export [chainName] [flags]

lux l2 import

Import L2 chain configuration.

lux l2 import [flags]

Subcommands:

• file: Import from a file
• running: Import from a running network
• historic: Import historic chain data

lux l2 publish

Publish L2 chain to a repository.

lux l2 publish [chainName] [flags]

lux l2 upgrade

Upgrade L2 chain VM or configuration.

lux l2 upgrade [subcommand]

Subcommands:

• apply: Apply an upgrade
• export: Export upgrade configuration
• generate: Generate upgrade configuration
• import: Import upgrade configuration
• print: Print upgrade information
• vm: Upgrade the VM

lux l2 stats

Show statistics for an L2 chain.

lux l2 stats [chainName]

lux l2 configure

Configure L2 chain parameters.

lux l2 configure [chainName] [flags]

lux l2 elastic

Manage elastic chains (dynamic validator sets).

lux l2 elastic [subcommand] [chainName]

lux l2 validators

List all validators for an L2 chain.

lux l2 validators [chainName]

lux l2 vmid

Get the VMID of an L2 chain.

lux l2 vmid [chainName]

L3 Commands

Create and manage L3s (app-specific chains) that run on top of L2s.

lux l3 create

Create a new L3 configuration.

lux l3 create [l3Name] [flags]

Flags:

• --l2 <string>: Parent L2 for this L3
• --vm <string>: VM type (evm, custom)
• Additional flags similar to L2 create

Examples:

# Create L3 on top of an L2
lux l3 create gaming-chain --l2 myL2 --vm custom

# Interactive creation
lux l3 create myL3

lux l3 deploy

Deploy an L3.

lux l3 deploy [l3Name] [flags]

Flags:

• --preconfirm: Enable pre-confirmations
• Additional deployment flags

lux l3 list

List all configured L3s.

lux l3 list

lux l3 describe

Show detailed information about an L3.

lux l3 describe [l3Name]

lux l3 bridge

Manage cross-chain bridges for L3s.

lux l3 bridge [subcommand] [l3Name]

Network Commands

Manage locally deployed networks.

lux network start

Start a local network.

lux network start [flags]

Flags:

• --node-version <string>: Use this version of node (default: "latest")
• --snapshot-name <string>: Name of snapshot to use (default: "default-1654102509")

Examples:

# Start with default settings
lux network start

# Start with specific node version
lux network start --node-version v1.17.12

# Start from custom snapshot
lux network start --snapshot-name my-snapshot

lux network stop

Stop the local network.

lux network stop

lux network clean

Clean the local network state.

lux network clean [flags]

Flags:

• --force: Force clean without confirmation

lux network status

Show the status of the local network.

lux network status

lux network quickstart

Quick start a local network with pre-configured settings.

lux network quickstart

Node Commands

Manage Lux node operations including development mode and automining.

lux node dev

Start a node in development mode.

lux node dev [flags]

lux node start

Start a node with specific configuration.

lux node start [flags]

lux node automine

Control automining on a running node.

lux node automine [subcommand]

Subcommands:

lux node automine start

Start automining.

lux node automine start [flags]

Flags:

• --rpc-url <string>: RPC URL of the node (default: "http://localhost:9630/v1/chain/C/rpc")
• --account <string>: Mining account address (default: "0x9011E888251AB053B7bD1cdB598Db4f9DEd94714")
• --private-key <string>: Private key for the mining account
• --threads <int>: Number of mining threads (default: 1)
• --monitor: Monitor block production

Examples:

# Start automining with default account
lux node automine start

# Start with custom account and monitor
lux node automine start --account 0x123... --monitor

# Start with multiple threads
lux node automine start --threads 4

lux node automine stop

Stop automining.

lux node automine stop [flags]

Flags:

• --rpc-url <string>: RPC URL of the node

lux node automine status

Check automining status.

lux node automine status [flags]

Flags:

• --rpc-url <string>: RPC URL of the node

lux node validator

Manage node validators.

lux node validator [subcommand]

Key Commands

Create and manage testnet signing keys. WARNING: These keys are NOT suitable for production/mainnet use.

lux key create

Create a new signing key.

lux key create [keyName] [flags]

Flags:

• --file <string>: Import the key from an existing key file
• -f, --force: Overwrite an existing key with the same name

Examples:

# Generate new key
lux key create myKey

# Import existing key
lux key create myKey --file ./existing-key.pk

# Force overwrite
lux key create myKey --force

lux key list

List all available keys.

lux key list

lux key delete

Delete a key.

lux key delete [keyName]

lux key export

Export a key to a file.

lux key export [keyName] [flags]

Transaction Commands

Sign and execute multisig transactions.

lux transaction sign

Sign a multisig transaction.

lux transaction sign [chainName] [flags]

Flags:

• --input-tx-filepath <string>: Path to the transaction file for signing
• -k, --key <string>: Select the key to use (testnet only)
• -g, --ledger: Use ledger instead of key
• --ledger-addrs <strings>: Use the given ledger addresses

Examples:

# Sign with key
lux transaction sign myChain --key myKey --input-tx-filepath tx.json

# Sign with ledger
lux transaction sign myChain --ledger --ledger-addrs addr1,addr2

lux transaction commit

Commit a signed transaction.

lux transaction commit [chainName] [flags]

Configuration Commands

Manage CLI configuration.

lux config

Show or modify configuration.

lux config [subcommand]

Subcommands:

• metrics: Configure metrics settings

Update Commands

Update the CLI to the latest version.

lux update

Check for and install updates.

lux update

Migration Commands

Migrate configurations between versions or networks.

lux migrate

Run migrations.

lux migrate [flags]

Configuration Files

The CLI uses several configuration files:

1. CLI Config: ~/.lux/cli.json - General CLI settings
2. Sidecar Files: ~/.cli/chains/<name>/sidecar.json - L1/L2/L3 chain configurations
3. Genesis Files: ~/.cli/chains/<name>/genesis.json - Genesis configurations
4. Node Config: Custom node configurations for local networks

Environment Variables

• RUN_E2E: Skip user metrics preference when set
• Standard Go proxy variables for downloading binaries

Common Workflows

Creating and Deploying an L1

# 1. Create L1 configuration
lux l1 create myL1 --proof-of-authority --token-name "MyToken" --token-symbol "MTK"

# 2. Deploy to local network
lux l1 deploy myL1 --local

# 3. Add validators
lux l1 validator add myL1 --node-id NodeID-...

Creating and Deploying an L2

# 1. Create L2 with Ethereum-based sequencing
lux chain create myL2 --evm --sequencer ethereum

# 2. Deploy to testnet
lux chain deploy myL2 --testnet

# 3. Add validators
lux l2 addValidator myL2

Setting Up Automining for Development

# 1. Start local network
lux network start

# 2. Start automining
lux node automine start --monitor

# 3. Check status
lux node automine status

Best Practices

1. Key Management: Never use CLI-generated keys on mainnet
2. Network Selection: Always verify the target network before deployment
3. Backups: Keep backups of important configurations and genesis files
4. Version Control: Track chain configurations in version control
5. Testing: Always test on local network before deploying to testnet/mainnet

Troubleshooting

Common Issues

1. Network not running: Start with lux network start
2. Port conflicts: Check for services using required ports
3. Missing dependencies: Ensure all required tools are installed
4. Permission errors: Check file permissions in ~/.cli/

Debug Mode

Enable debug logging:

lux --log-level DEBUG [command]

Getting Help

Each command has built-in help:

lux [command] --help
lux [command] [subcommand] --help