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

# Update

> Update Lager Box code from GitHub repository

Update Lager Box software on Lagerboxes with comprehensive progress tracking and automatic configuration.

## Syntax

```bash theme={null}
lager update [OPTIONS]
```

## Options

| Option              | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `--box BOX`         | Lagerbox name or IP address                           |
| `--all`             | Update all saved boxes that need updating             |
| `--version VERSION` | Lager Box version/branch to update to (default: main) |
| `--yes`             | Skip confirmation prompt                              |
| `--skip-restart`    | Skip container restart after update                   |
| `--check-jlink`     | Check for J-Link and offer to install if missing      |
| `--force`           | Force fresh Docker build by removing cached image     |
| `--verbose` / `-v`  | Show detailed output (default shows progress bar)     |

<Note>
  Either `--box` or `--all` is required. They cannot be used together.
</Note>

## Usage

### Basic Update

```bash theme={null}
# Update to latest main branch
lager update --box my-lager-box --yes

# Update to staging branch
lager update --box my-lager-box --version staging --yes

# Update with verbose output
lager update --box my-lager-box --yes --verbose

# Force fresh Docker build (use for major code changes)
lager update --box my-lager-box --force --yes
```

### Update All Boxes

The `--all` flag queries every saved box's version and updates only those that are behind the current CLI version.

```bash theme={null}
# Update all boxes that need updating
lager update --all --yes

# Preview which boxes need updating (without --yes, shows confirmation)
lager update --all
```

**How `--all` works:**

1. Queries each saved box's `/cli-version` endpoint
2. Compares box version against the current CLI version
3. Builds a list of boxes that need updating (version older than CLI or unknown)
4. Skips boxes that are already current, newer, or unreachable
5. Updates each box sequentially
6. Displays a summary of successes and failures

**Example output:**

```
CLI version: 0.3.22

Checking box versions...

  lab-box-1    0.3.20  will update
  lab-box-2    0.3.22  current
  pi-box       0.3.19  will update
  offline-box  ---     unreachable (skipped)

2 box(es) need updating. Proceed? [Y/n]: y

Updating lab-box-1...
  [OK] Updated to 0.3.22

Updating pi-box...
  [OK] Updated to 0.3.22

Update complete (45.2s total)
  Successful: 2
  Failed:     0
```

### Skip Container Restart

```bash theme={null}
# Update code but don't restart containers
lager update --box my-lager-box --skip-restart --yes

# Manually restart later
ssh lagerdata@my-lager-box 'cd ~/box && ./start_box.sh'
```

### J-Link Installation Check

```bash theme={null}
# Check if J-Link is installed, offer to install if missing
lager update --box my-lager-box --check-jlink --yes
```

***

## Update Process

The update command performs the following steps (shown in progress bar):

1. **SSH Connection** - Establish secure connection to Lager Box
2. **Git Repository Check** - Validate lager repository exists
3. **Git Pull** - Pull latest code from specified branch
4. **Udev Rules** - Install USB instrument access rules
5. **Docker Build** - Build updated containers (no-cache)
6. **Firewall Setup** - Configure UFW if needed
7. **Customer Binaries** - Set up custom binaries directory
8. **J-Link Check** - Verify debug probe software (optional)
9. **Version Update** - Record version in `/etc/lager/version`
10. **Container Restart** - Start updated containers
11. **Status Verification** - Confirm containers are running

***

## Version Tracking

The Lager Box tracks its current version in `/etc/lager/version`. You can sync versions from all Lager Boxes:

```bash theme={null}
# Sync versions from all configured boxes
lager boxes sync
```

***

## SSH Key Authentication

The update command automatically detects SSH key configuration:

* **With SSH keys**: Updates proceed without password prompts
* **Without SSH keys**: Prompts for password (interactive mode)

To set up SSH keys:

```bash theme={null}
ssh-copy-id lagerdata@<box-ip>
```

***

## Firewall Auto-Configuration

If UFW is not configured, the update command will:

1. Detect missing firewall rules
2. Offer to install and configure UFW
3. Apply secure defaults (VPN-only access to Lager ports)

```bash theme={null}
# Manual firewall configuration
cli/deployment/security/secure_box_firewall.sh <box-ip>
```

***

## Examples

```bash theme={null}
# Standard update workflow
lager update --box lab-lager-box --version main --yes

# Update all boxes at once
lager update --all --yes

# Update all boxes to staging branch
lager update --all --version staging --yes

# Force fresh build on a specific box
lager update --box my-lager-box --force --yes

# Verbose update for troubleshooting
lager update --box my-lager-box --verbose
```

***

## Troubleshooting

### Update Fails at Git Pull

```bash theme={null}
# Check the remote URL (should be HTTPS, not SSH)
ssh lagerdata@<box-ip> 'cd ~/box && git remote get-url origin'

# If it shows git@github.com:..., switch to HTTPS:
ssh lagerdata@<box-ip> 'cd ~/box && git remote set-url origin https://github.com/lagerdata/lager.git'
```

### Container Build Fails

```bash theme={null}
# SSH in and check Docker status
ssh lagerdata@<box-ip>
docker ps -a
docker logs controller
```

### Firewall Issues

```bash theme={null}
# Check firewall status
ssh lagerdata@<box-ip> 'sudo ufw status verbose'

# Re-run firewall setup
cli/deployment/security/secure_box_firewall.sh <box-ip>
```

***

## Notes

* Progress bar is disabled when `--verbose` is used
* Container builds use `--no-cache` to ensure fresh builds
* Version defaults to `main` if not specified
* Update automatically verifies container health after restart
* `--all` checks versions automatically and only updates outdated boxes
* `--force` removes cached Docker images before building (useful after major code changes)
* `--box` and `--all` are mutually exclusive