CLI Usage

Complete reference for all Lightfold CLI commands

Primary Command

lightfold deploy

Full deployment orchestration (recommended for most users).

# Deploy current directory
lightfold deploy

# Deploy specific path
lightfold deploy ~/Projects/myapp

Flags:

• --target - Deploy to named target
• --builder - Force builder choice (native, nixpacks, dockerfile)
• --force - Rerun all steps regardless of state
• --dry-run - Preview execution plan without running

What it does:

1. Detects framework
2. Creates infrastructure (if needed)
3. Configures server (if needed)
4. Deploys code changes

Advanced Commands

lightfold create

Create infrastructure only.

# Auto-provision on DigitalOcean
lightfold create --target myapp --provider digitalocean --region nyc1 --size s-1vcpu-1gb

# Use your own server (BYOS)
lightfold create --target myapp --provider byos --ip 1.2.3.4 --user deploy --ssh-key ~/.ssh/id_rsa

Flags:

• --target - Target name (required)
• --provider - Provider choice (digitalocean, vultr, hetzner, byos)
• --region - Cloud provider region (for auto-provision)
• --size - Server size (for auto-provision)
• --ip - Server IP (for BYOS)
• --user - SSH username (for BYOS)
• --ssh-key - SSH key path (for BYOS)

lightfold configure

Configure server only.

# Configure current directory
lightfold configure

# Configure specific target
lightfold configure --target myapp

# Force reconfiguration
lightfold configure --target myapp --force

Flags:

• --target - Target name
• --force - Reconfigure even if already configured

What it does:

• Installs runtime dependencies
• Sets up systemd services
• Configures nginx
• Creates deployment directory structure

lightfold push

Deploy code changes only.

# Push current directory
lightfold push

# Push specific target
lightfold push --target myapp

# Force deployment
lightfold push --target myapp --force

Flags:

• --target - Target name
• --force - Deploy even if commit unchanged

What it does:

• Checks git commit changes
• Creates timestamped release
• Uploads and builds code
• Blue/green deployment with health checks

Management Commands

lightfold status

View deployment status and server health.

# List all targets
lightfold status

# Show current directory status
lightfold status .

# Show specific target status
lightfold status --target myapp

# JSON output
lightfold status --target myapp --json

Flags:

• --target - Target name
• --json - Output in JSON format

lightfold logs

View application logs.

# View logs for current directory
lightfold logs

# Stream logs in real-time
lightfold logs --tail

# Last 200 lines
lightfold logs --lines 200

# Specific target
lightfold logs --target myapp --tail

Flags:

• --target - Target name
• --tail - Stream logs in real-time
• --lines - Number of lines to show (default: 100)

lightfold rollback

Rollback to previous release.

# Rollback current directory
lightfold rollback

# Rollback specific target
lightfold rollback --target myapp

# Skip confirmation
lightfold rollback --force

Flags:

• --target - Target name
• --force - Skip confirmation prompt

lightfold sync

Sync local state/config with actual server state (drift recovery).

# Sync current directory
lightfold sync

# Sync specific target
lightfold sync --target myapp

Flags:

• --target - Target name

Use cases:

• Local state files corrupted or deleted
• Server IP changed
• Recovering from bad state
• After manual server changes

lightfold ssh

SSH into deployment target.

lightfold ssh --target myapp

Flags:

• --target - Target name (required)

lightfold destroy

Destroy VM and remove local configuration.

lightfold destroy --target myapp

Flags:

• --target - Target name (required)

Warning: This will permanently delete your server and all data.

Configuration Commands

lightfold config

Manage targets and API tokens.

# List all targets
lightfold config list

# Set API token
lightfold config set-token digitalocean

# Get API token
lightfold config get-token digitalocean

lightfold domain

Manage custom domains and SSL.

# Add domain to current directory
lightfold domain add --domain example.com

# Add domain to specific target
lightfold domain add --domain example.com --target myapp

# Remove domain
lightfold domain remove --target myapp

# Show domain config
lightfold domain show --target myapp

Flags:

• --domain - Domain name (for add command)
• --target - Target name

Utility Commands

lightfold detect

Detect framework only (no deployment).

# Detect current directory
lightfold detect

# Detect specific path
lightfold detect ~/Projects/myapp

# JSON output
lightfold detect --json

Flags:

• --json - Output in JSON format

lightfold keygen

Generate SSH keypair.

lightfold keygen

Invocation Patterns

All commands support three invocation patterns:

1. Current directory (default):

   lightfold deploy
   

2. Specific path:

   lightfold deploy ~/Projects/myapp
   

3. Named target:

   lightfold deploy --target myapp