Boxes

Manage Lagerbox names, IP addresses, and configurations for local development.

Syntax

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
`lock`	Lock a box to prevent others from using it
`unlock`	Unlock 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:

Runs tailscale status to discover devices
Filters for devices with names 5-8 characters long
Converts names to uppercase
Skips boxes that already exist with the same IP
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:

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.

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

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Development

Utilities

Syntax

Commands

Command Reference

`add`

`add-all`

`delete`

`edit`

`list`

`delete-all`

`export`

`import`

`lock`

`unlock`

Configuration Storage

Validation

Examples

Notes

​Syntax

​Commands

​Command Reference

​add

​add-all

​delete

​edit

​list

​delete-all

​export

​import

​lock

​unlock

​Configuration Storage

​Validation

​Examples

​Notes

Syntax

Commands

Command Reference

`add`

`add-all`

`delete`

`edit`

`list`

`delete-all`

`export`

`import`

`lock`

`unlock`

Configuration Storage

Validation

Examples

Notes