> ## 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. # Boxes > Manage Lagerbox configurations Manage Lagerbox names, IP addresses, and configurations for local development. ## Syntax ```bash theme={null} lager boxes COMMAND [OPTIONS] ``` ## Commands | Command | Description | | ------------ | ------------------------------------------ | | `add` | Add a new box configuration | | `add-all` | Add all boxes from Tailscale network | | `delete` | Delete a box configuration | | `edit` | Edit an existing box configuration | | `list` | List all configured boxes | | `delete-all` | Delete all box configurations | | `export` | Export box configuration to JSON | | `import` | Import box configuration from JSON | | `sync` | Sync Lager Box versions from all boxes | | `lock` | Lock a box to prevent others from using it | | `unlock` | Unlock a box | *** ## Command Reference ### `add` Add a new Lagerbox configuration. ```bash theme={null} lager boxes add --name NAME --ip IP [OPTIONS] ``` **Options:** * `--name` (required) - Name to assign to the box * `--ip` (required) - IP address of the box * `--user` - SSH username (default: lagerdata) * `--version` - Lager Box version/branch (e.g., staging, main) * `--yes` - Confirm without prompting **Examples:** ```bash theme={null} # Add a basic box lager boxes add --name lab-lager-box --ip # Add with custom username lager boxes add --name pi-lager-box --ip --user pi # Add with version tracking lager boxes add --name staging-lager-box --ip --version staging ``` ### `add-all` Automatically add all Lagerboxes found on your Tailscale network. ```bash theme={null} lager boxes add-all [--yes] ``` **Options:** * `--yes` - Confirm without prompting This command scans your Tailscale network for devices with names 5-8 characters long (typical Lagerbox naming convention) and automatically adds them as boxes with uppercase names. **How it works:** 1. Runs `tailscale status` to discover devices 2. Filters for devices with names 5-8 characters long 3. Converts names to uppercase 4. Skips boxes that already exist with the same IP 5. Adds new boxes to your configuration **Example:** ```bash theme={null} # Scan and add all boxes lager boxes add-all # Output: Scanning Tailscale network for lager boxes... Found 3 lager box(es): LABGW1 → TESTGW → DEVBOX → Add all 3 box(es)? [Y/n]: y LABGW1: added TESTGW: added DEVBOX: already exists (skipped) Summary: Added: 2 Skipped: 1 [OK] Successfully added 2 box(es) ``` ```bash theme={null} # Add without confirmation prompt lager boxes add-all --yes ``` ### `delete` Delete a box configuration. ```bash theme={null} lager boxes delete --name NAME [--yes] ``` **Examples:** ```bash theme={null} # Delete with confirmation prompt lager boxes delete --name old-lager-box # Delete without confirmation lager boxes delete --name old-lager-box --yes ``` ### `edit` Edit an existing box configuration. ```bash theme={null} lager boxes edit --name NAME [OPTIONS] ``` **Options:** * `--name` (required) - Name of the box to edit * `--ip` - New IP address * `--user` - New SSH username * `--version` - New Lager Box version/branch * `--new-name` - Rename the box * `--yes` - Confirm without prompting **Examples:** ```bash theme={null} # Change IP address lager boxes edit --name lab-lager-box --ip # Rename a box lager boxes edit --name old-name --new-name new-name # Update SSH user and version lager boxes edit --name pi-lager-box --user pi --version staging ``` ### `list` List all configured boxes with live version status. This is also the default behavior when running `lager boxes` with no subcommand. ```bash theme={null} lager boxes list lager boxes # same as list ``` The command queries each box's `/cli-version` endpoint to display real-time version and status information. **Output:** ``` CLI version: 0.3.22 ┌─────────────┬─────────────────┬───────────┬─────────┬───────────────┐ │ Name │ IP │ User │ Version │ Status │ ├─────────────┼─────────────────┼───────────┼─────────┼───────────────┤ │ lab-box-1 │ │ lagerdata │ 0.3.22 │ current │ │ lab-box-2 │ │ lagerdata │ 0.3.20 │ needs update │ │ pi-box │ │ pi │ 0.3.23 │ newer │ │ offline-box │ │ lagerdata │ --- │ unreachable │ └─────────────┴─────────────────┴───────────┴─────────┴───────────────┘ Summary: 1 current, 1 needs update, 1 newer, 1 unreachable ``` **Status Colors:** | Status | Color | Meaning | | -------------- | ------ | -------------------------------------- | | `current` | Green | Box version matches CLI version | | `needs update` | Yellow | Box version is older than CLI | | `newer` | Cyan | Box version is newer than CLI | | `unreachable` | Red | Box could not be contacted | | `timeout` | Red | Connection timed out | | `old box` | Red | Box does not support version reporting | ### `delete-all` Delete all box configurations. ```bash theme={null} lager boxes delete-all [--yes] ``` ### `export` Export box configuration to JSON file. ```bash theme={null} lager boxes export [--output FILE] ``` **Options:** * `--output` / `-o` - Output file path (prints to stdout if not specified) **Examples:** ```bash theme={null} # Export to file lager boxes export --output boxes.json # Export to stdout lager boxes export ``` ### `import` Import box configuration from JSON file. ```bash theme={null} lager boxes import FILE [--merge] [--yes] ``` **Options:** * `FILE` - Path to JSON file to import * `--merge` - Merge with existing boxes (default: replace) * `--yes` - Confirm without prompting **Examples:** ```bash theme={null} # Replace all boxes with imported config lager boxes import boxes.json --yes # Merge imported boxes with existing lager boxes import new-boxes.json --merge --yes ``` ### `sync` Sync Lager Box versions from all configured boxes. ```bash theme={null} lager boxes sync [--port PORT] [--timeout SECONDS] ``` **Options:** * `--port` - Lager Box HTTP port (default: 5000) * `--timeout` - HTTP request timeout in seconds (default: 5) This command queries each Lager Box's current version and updates the local configuration. ### `lock` Lock a box to prevent other users from using it. See [Box Locking](/source/reference/cli/locking) for full details. ```bash theme={null} lager boxes lock --box NAME ``` **Options:** * `--box` (required) - Name of the box to lock **Example:** ```bash theme={null} lager boxes lock --box lab-box ``` ### `unlock` Unlock a box to allow other users to use it. See [Box Locking](/source/reference/cli/locking) for full details. ```bash theme={null} lager boxes unlock --box NAME [--force] ``` **Options:** * `--box` (required) - Name of the box to unlock * `--force` - Force unlock even if locked by another user **Examples:** ```bash theme={null} # Unlock your own lock lager boxes unlock --box lab-box # Force unlock another user's lock lager boxes unlock --box lab-box --force ``` *** ## Configuration Storage Box configurations are stored in `.lager` file in your project directory: ```json theme={null} { "boxes": { "lab-box-1": { "ip": "", "user": "lagerdata", "version": "main" }, "pi-box": "" } } ``` Entries can be: * **Simple**: Just an IP address string * **Full**: Object with ip, user, and version fields *** ## Validation The boxes commands perform validation: * **Duplicate detection**: Prevents adding boxes with same name or IP * **IP validation**: Validates IP address format * **Confirmation**: Shows before/after state for edit operations *** ## Examples ```bash theme={null} # Set up a new lab lager boxes add --name lager-box-1 --ip lager boxes add --name lager-box-2 --ip lager boxes add --name lager-box-3 --ip # Export configuration for team sharing lager boxes export -o lab-config.json # Import on another machine lager boxes import lab-config.json --yes # Sync versions after updates lager boxes sync # Clean up lager boxes delete-all --yes ``` *** ## Notes * Box names must be unique * IP addresses must be unique (no duplicate IPs) * The default SSH user is `lagerdata` * Use `--merge` when importing to preserve existing boxes * Sync command requires Lager Boxes to be online and accessible