Skip to main content
Manage Lagerbox names, IP addresses, and configurations for local development.

​
Syntax

lager boxes COMMAND [OPTIONS]

​
Commands

CommandDescription
addAdd a new box configuration
add-allAdd all boxes from Tailscale network
deleteDelete a box configuration
editEdit an existing box configuration
listList all configured boxes
delete-allDelete all box configurations
exportExport box configuration to JSON
importImport box configuration from JSON
syncSync Lager Box versions from all boxes

​
Command Reference

​
add

Add a new Lagerbox configuration. 
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: 
# Add a basic box
lager boxes add --name lab-lager-box --ip <BOX_IP>

# Add with custom username
lager boxes add --name pi-lager-box --ip <BOX_IP> --user pi

# Add with version tracking
lager boxes add --name staging-lager-box --ip <BOX_IP> --version staging

​
add-all

Automatically add all Lagerboxes found on your Tailscale network. 
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: 
# Scan and add all boxes
lager boxes add-all

# Output:
Scanning Tailscale network for lager boxes...

Found 3 lager box(es):

  LABGW1 → <BOX_IP>
  TESTGW → <BOX_IP>
  DEVBOX → <BOX_IP>

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)

# Add without confirmation prompt
lager boxes add-all --yes

​
delete

Delete a box configuration. 
lager boxes delete --name NAME [--yes]
Examples: 
# 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. 
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: 
# Change IP address
lager boxes edit --name lab-lager-box --ip <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. 
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   │ <BOX_IP>        │ lagerdata │ 0.3.22  │ current       │
│ lab-box-2   │ <BOX_IP>        │ lagerdata │ 0.3.20  │ needs update  │
│ pi-box      │ <BOX_IP>        │ pi        │ 0.3.23  │ newer         │
│ offline-box │ <BOX_IP>        │ lagerdata │ ---     │ unreachable   │
└─────────────┴─────────────────┴───────────┴─────────┴───────────────┘

Summary: 1 current, 1 needs update, 1 newer, 1 unreachable
Status Colors:
StatusColorMeaning
currentGreenBox version matches CLI version
needs updateYellowBox version is older than CLI
newerCyanBox version is newer than CLI
unreachableRedBox could not be contacted
timeoutRedConnection timed out
old boxRedBox does not support version reporting

​
delete-all

Delete all box configurations. 
lager boxes delete-all [--yes]

​
export

Export box configuration to JSON file. 
lager boxes export [--output FILE]
Options:
  • --output / -o - Output file path (prints to stdout if not specified)
Examples: 
# Export to file
lager boxes export --output boxes.json

# Export to stdout
lager boxes export

​
import

Import box configuration from JSON file. 
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: 
# 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. 
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.

​
Configuration Storage

Box configurations are stored in .lager file in your project directory: 
{
  "boxes": {
    "lab-box-1": {
      "ip": "<BOX_IP>",
      "user": "lagerdata",
      "version": "main"
    },
    "pi-box": "<BOX_IP>"
  }
}
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

# Set up a new lab
lager boxes add --name lager-box-1 --ip <BOX_IP>
lager boxes add --name lager-box-2 --ip <BOX_IP>
lager boxes add --name lager-box-3 --ip <BOX_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