> ## Documentation Index
> Fetch the complete documentation index at: https://lightfold.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Usage

> Complete reference for all Lightfold CLI commands

## Primary Command

### `lightfold deploy`

Full deployment orchestration (recommended for most users).

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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).

```bash theme={null}
# 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.

```bash theme={null}
lightfold ssh --target myapp
```

**Flags:**

* `--target` - Target name (required)

### `lightfold destroy`

Destroy VM and remove local configuration.

```bash theme={null}
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.

```bash theme={null}
# 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.

```bash theme={null}
# 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).

```bash theme={null}
# 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.

```bash theme={null}
lightfold keygen
```

## Invocation Patterns

All commands support three invocation patterns:

1. **Current directory** (default):
   ```bash theme={null}
   lightfold deploy
   ```

2. **Specific path**:
   ```bash theme={null}
   lightfold deploy ~/Projects/myapp
   ```

3. **Named target**:
   ```bash theme={null}
   lightfold deploy --target myapp
   ```