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
lockLock a box to prevent others from using it
unlockUnlock a box

​
Command Reference

​
add

Add a new Lagerbox configuration. 
lager boxes add --name NAME --ip IP --user USER [OPTIONS]
Options:
  • --name (required) - Name to assign to the box
  • --ip (required) - IP address of the box
  • --user (required) - SSH username for the box (the account you log in as)
  • --version - Lager Box version/branch (e.g., staging, main)
  • --yes - Confirm without prompting
--user is required. It previously defaulted to lagerdata, but since most boxes use a different login account, the default was removed so the correct user is always recorded for SSH, updates, and lager ssh.
Examples: 
# Add a basic box
lager boxes add --name my-lager-box --ip <BOX_IP> --user lager

# Add with a Raspberry Pi default account
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> --user lager --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 my-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        │
├──────────────┼─────────────────┼───────────┼─────────┼───────────────┤
│ my-lager-box │ <BOX_IP>        │ lagerdata │ 0.3.22  │ current       │
│ staging-box  │ <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

​
lock

Lock a box to prevent other users from using it. See Box Locking for full details. 
lager boxes lock --box NAME
Options:
  • --box (required) - Name of the box to lock
Example: 
lager boxes lock --box my-lager-box

​
unlock

Unlock a box to allow other users to use it. See Box Locking for full details. 
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: 
# Unlock your own lock
lager boxes unlock --box my-lager-box

# Force unlock another user's lock
lager boxes unlock --box my-lager-box --force

​
Configuration Storage

Box configurations are stored in .lager file in your project directory: 
{
  "boxes": {
    "my-lager-box": {
      "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 bench
lager boxes add --name my-lager-box --ip <BOX_IP> --user lager
lager boxes add --name staging-box --ip <BOX_IP> --user lager
lager boxes add --name pi-box --ip <BOX_IP> --user lager

# Export configuration for team sharing
lager boxes export -o bench-config.json

# Import on another machine
lager boxes import bench-config.json --yes

# Clean up
lager boxes delete-all --yes

​
Notes

  • Box names must be unique
  • IP addresses must be unique (no duplicate IPs)
  • --user is required when adding a box (there is no default SSH user)
  • Use --merge when importing to preserve existing boxes
  • Sync command requires Lager Boxes to be online and accessible