CLI Commands Reference

Complete command reference for the Light Protocol CLI. All commands use the format:

light <command> [flags]

Configuration

config

Initialize or update configuration values for RPC endpoints.

light config [--solanaRpcUrl <url>] [--indexerUrl <url>] [--proverUrl <url>] [--get]

--solanaRpcUrl

string

Solana RPC URL endpoint

--indexerUrl

string

Photon indexer URL endpoint

--proverUrl

string

Light prover server URL endpoint

--get

boolean

Display current configuration values

light config --get

Configuration is stored at ~/.config/light/config.json by default. Override with LIGHT_PROTOCOL_CONFIG environment variable.

init

Initialize a new compressed account project from a template.

light init <name>

name

string

required

The name of the project. Will be converted to kebab-case for directory name, snake_case for Rust, and PascalCase for types.

light init my-compressed-app

What gets created: The init command scaffolds a complete Solana program project with:

Anchor program with Light Protocol integration
TypeScript client with @lightprotocol/stateless.js setup
Test suite configuration
All required dependencies at compatible versions

On macOS, you may need to set CPATH before building:

echo 'export CPATH="/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include:$CPATH"' >> ~/.zshrc && source ~/.zshrc

Project structure:

my-compressed-app/
├── programs/           # Anchor programs
├── app/               # TypeScript client
├── tests/             # Integration tests
├── Anchor.toml        # Anchor configuration
└── package.json       # Node dependencies

Token Management

create-mint

Create a new compressed token mint.

light create-mint [--mint-keypair <path>] [--mint-authority <address>] [--mint-decimals <number>]

--mint-keypair

string

Path to mint keypair file. If not provided, a random keypair is generated.

--mint-authority

string

Address of the mint authority. Defaults to the fee payer.

--mint-decimals

integer

default:"9"

Number of decimal places (base 10 digits right of decimal).

light create-mint

mint-to

Mint compressed tokens to a recipient address.

light mint-to --mint <address> --to <address> --amount <number> [--mint-authority <path>]

--mint

string

required

Mint address

--to

string

required

Recipient address

--amount

integer

required

Amount to mint in tokens (respects mint decimals)

--mint-authority

string

Filepath to mint authority keypair. Defaults to local Solana wallet.

light mint-to \
  --mint DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 \
  --to 7tEr3KHXFxnK4CqmVtzq3JLqnHHp8zEkeFQq9J4bLxKQ \
  --amount 1000000000

approve-and-mint-to

Mint tokens to a compressed account via external mint authority. Similar to mint-to but designed for scenarios with delegated minting authority.

light approve-and-mint-to --mint <address> --to <address> --amount <number> [--mint-authority <path>]

--mint

string

required

Mint address

--to

string

required

Recipient address

--amount

integer

required

Amount to mint in tokens

--mint-authority

string

Filepath to mint authority keypair. Defaults to local Solana wallet.

Example

light approve-and-mint-to \
  --mint DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 \
  --to 7tEr3KHXFxnK4CqmVtzq3JLqnHHp8zEkeFQq9J4bLxKQ \
  --amount 1000000000 \
  --mint-authority ./keys/external-authority.json

transfer

Transfer compressed tokens from one account to another.

light transfer --mint <address> --to <address> --amount <number> [--fee-payer <path>]

--mint

string

required

Mint address to transfer

--to

string

required

Recipient address

--amount

integer

required

Amount to send in tokens

--fee-payer

string

Fee payer account keypair path. Defaults to local Solana wallet.

light transfer \
  --mint DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 \
  --to 7tEr3KHXFxnK4CqmVtzq3JLqnHHp8zEkeFQq9J4bLxKQ \
  --amount 1000000

create-token-pool

light create-token-pool --mint <address>

--mint

string

required

Base58-encoded mint address to register

Example

light create-token-pool \
  --mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

This creates the interface required for compressing and decompressing an existing SPL token mint.

Compression Operations

compress-sol

Compress native SOL into a compressed account.

light compress-sol --to <address> --amount <lamports>

--to

string

required

Recipient address for the compressed SOL

--amount

integer

required

Amount to compress in lamports (1 SOL = 1,000,000,000 lamports)

light compress-sol \
  --to 7tEr3KHXFxnK4CqmVtzq3JLqnHHp8zEkeFQq9J4bLxKQ \
  --amount 10000000

decompress-sol

Decompress compressed SOL back to native SOL.

light decompress-sol --to <address> --amount <lamports>

--to

string

required

Recipient address for the decompressed SOL

--amount

integer

required

Amount to decompress in lamports

Example

light decompress-sol \
  --to 7tEr3KHXFxnK4CqmVtzq3JLqnHHp8zEkeFQq9J4bLxKQ \
  --amount 10000000

compress-spl

Compress SPL tokens into compressed token accounts.

light compress-spl --mint <address> --to <address> --amount <number>

--mint

string

required

SPL token mint address

--to

string

required

Recipient address (owner of destination compressed token account)

--amount

integer

required

Amount to compress in tokens

Example

light compress-spl \
  --mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --to 7tEr3KHXFxnK4CqmVtzq3JLqnHHp8zEkeFQq9J4bLxKQ \
  --amount 1000000

The source is the associated token account of the fee payer. Ensure sufficient SPL token balance before compressing.

decompress-spl

Decompress compressed tokens back into SPL tokens.

light decompress-spl --mint <address> --to <address> --amount <number>

--mint

string

required

Token mint address

--to

string

required

Recipient address (owner of destination token account)

--amount

integer

required

Amount to decompress in tokens

Example

light decompress-spl \
  --mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --to 7tEr3KHXFxnK4CqmVtzq3JLqnHHp8zEkeFQq9J4bLxKQ \
  --amount 1000000

If the recipient’s associated token account doesn’t exist, it will be created automatically.

Account Queries

balance

Get compressed SOL balance for an address.

light balance --owner <address>

--owner

string

required

Address to check balance for

Example

light balance --owner 7tEr3KHXFxnK4CqmVtzq3JLqnHHp8zEkeFQq9J4bLxKQ

Output:

Compressed SOL balance: 1000000000

token-balance

Get compressed token balance for a specific mint and owner.

light token-balance --mint <address> --owner <address>

--mint

string

required

Mint address of the compressed token

--owner

string

required

Address of the token account owner

Example

light token-balance \
  --mint DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 \
  --owner 7tEr3KHXFxnK4CqmVtzq3JLqnHHp8zEkeFQq9J4bLxKQ

Output:

Balance: 1000000000

If no token accounts are found, the command returns a balance of 0.

merge-token-accounts

Consolidate all compressed token accounts for a specific mint into a single account.

light merge-token-accounts --mint <address> [--fee-payer <path>]

--mint

string

required

Mint address to merge accounts for

--fee-payer

string

Fee payer account keypair path. Defaults to local Solana wallet.

Example

light merge-token-accounts \
  --mint DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

Merging reduces the number of accounts, which can improve performance and reduce transaction complexity for future operations.

Development Tools

test-validator

Start a local test environment with validator, indexer, and prover. See the Test Validator page for complete documentation.

light test-validator [flags]

Common flags:

--skip-indexer - Run without Photon indexer
--skip-prover - Run without prover service
--forester - Enable forester service
--rpc-port <port> - Custom RPC port (default: 8899)
--devnet - Clone Devnet state
--mainnet - Clone Mainnet state
--stop - Stop the validator

Example

light test-validator --forester --verbose

start-prover

Start a standalone prover server for generating zero-knowledge proofs.

light start-prover [--prover-port <port>] [--redisUrl <url>]

--prover-port

integer

default:"3001"

Port for the Light prover server

--redisUrl

string

Redis URL for the prover (e.g., redis://localhost:6379). Can also be set via REDIS_URL environment variable.

light start-prover

The prover performs a health check on startup. If it fails, check that all required binaries are present and accessible.

Common Workflows

Complete Token Lifecycle

Start Test Environment

light test-validator

Create Mint

light create-mint --mint-decimals 9

Note the mint address from the output.

Mint Tokens

light mint-to \
  --mint <MINT_ADDRESS> \
  --to $(solana address) \
  --amount 1000000000

Check Balance

light token-balance \
  --mint <MINT_ADDRESS> \
  --owner $(solana address)

Transfer Tokens

light transfer \
  --mint <MINT_ADDRESS> \
  --to <RECIPIENT_ADDRESS> \
  --amount 100000000

Compress Existing SPL Tokens

light create-token-pool --mint <EXISTING_MINT>

Compress Tokens

light compress-spl \
  --mint <EXISTING_MINT> \
  --to $(solana address) \
  --amount 1000000

Verify

light token-balance \
  --mint <EXISTING_MINT> \
  --owner $(solana address)

Work with Compressed SOL

Compress SOL

light compress-sol \
  --to $(solana address) \
  --amount 100000000

Check Balance

light balance --owner $(solana address)

Decompress SOL

light decompress-sol \
  --to $(solana address) \
  --amount 50000000

Tips and Best Practices

Use environment variables for addresses

Save frequently used addresses as environment variables:

export MINT_ADDRESS="DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"
export RECIPIENT="7tEr3KHXFxnK4CqmVtzq3JLqnHHp8zEkeFQq9J4bLxKQ"

light transfer --mint $MINT_ADDRESS --to $RECIPIENT --amount 1000

Check balances after operations

Always verify balances after compression/decompression:

# After compress-sol
light balance --owner $(solana address)

# After compress-spl
light token-balance --mint $MINT --owner $(solana address)

Use decimal conversion for token amounts

For a mint with 9 decimals:

1 token = 1,000,000,000 (1e9)
0.1 tokens = 100,000,000 (1e8)
0.001 tokens = 1,000,000 (1e6)

For a mint with 6 decimals (like USDC):

1 token = 1,000,000 (1e6)
0.1 tokens = 100,000 (1e5)

Keep test validator running

The test validator maintains state between commands. Don’t restart unless needed:

# Start once
light test-validator

# In another terminal, run commands
light create-mint
light mint-to ...
light transfer ...

Save transaction IDs

Save transaction signatures for reference:

light mint-to ... > tx.log

# Or extract with grep
light mint-to ... | grep "txId" > transactions.txt

Getting Help

Every command supports the --help flag:

light --help                 # List all commands
light transfer --help        # Get detailed help for transfer
light test-validator --help  # Get detailed help for test-validator

Next Steps

Test Validator

Deep dive into local development setup

Compressed Tokens

Build applications with compressed tokens

JavaScript SDK

Integrate with your JavaScript apps

Documentation Index

​CLI Commands Reference

​Configuration

​config

​init

​Token Management

​create-mint

​mint-to

​approve-and-mint-to

​transfer

​create-token-pool

​Compression Operations

​compress-sol

​decompress-sol

​compress-spl

​decompress-spl

​Account Queries

​balance

​token-balance

​merge-token-accounts

​Development Tools

​test-validator

​start-prover

​Common Workflows

​Complete Token Lifecycle

​Compress Existing SPL Tokens

​Work with Compressed SOL

​Tips and Best Practices

​Getting Help

​Next Steps

Test Validator

Compressed Tokens

JavaScript SDK

CLI Commands Reference

Configuration

config

init

Token Management

create-mint

mint-to

approve-and-mint-to

transfer

create-token-pool

Compression Operations

compress-sol

decompress-sol

compress-spl

decompress-spl

Account Queries

balance

token-balance

merge-token-accounts

Development Tools

test-validator

start-prover

Common Workflows

Complete Token Lifecycle

Compress Existing SPL Tokens

Work with Compressed SOL

Tips and Best Practices

Getting Help

Next Steps