# CLI Reference

Complete reference documentation for the microsandbox command-line interface.

# Installation

curl -sSL https://get.microsandbox.dev | sh

# Quick Start

# Start the server in development mode
msb server start --dev

# Global Options

Flag	Description
`-V, --version`	Show version
`--error`	Show logs with error level
`--warn`	Show logs with warn level
`--info`	Show logs with info level
`--debug`	Show logs with debug level
`--trace`	Show logs with trace level

# Server Management

Start the sandbox server.

msb server start [options]

Option	Description
`--host <host>`	Host to listen on
`--port <port>`	Port to listen on
`-p, --path <path>`	Namespace directory path
`--dev`	Run in development mode
`-k, --key <key>`	Set secret key
`-d, --detach`	Run in background
`-r, --reset-key`	Reset the server key

Examples:

# Start server in development mode
msb server start --dev

# Start server on custom port
msb server start --port 8080

# Start server on custom host
msb server start --host 0.0.0.0

# Start server in background with custom namespace path
msb server start --detach --path /custom/namespaces

# Start server with a specific key
msb server start --key mySecretKey123

Generate a new API key.

msb server keygen [options]

Option	Description
`--expire <duration>`	Token expiration (1s, 2m, 3h, etc.)
`-n, --namespace <ns>`	Namespace for the API key

Examples:

# Generate an API key for all namespaces
msb server keygen

# Generate an API key that expires in 24 hours, for all namespaces
msb server keygen --expire 24h

# Generate an API key for a specific namespace
msb server keygen --namespace production

# Generate a short-lived key for testing
msb server keygen --expire 30m --namespace testing

Show server status.

msb server status [--sandbox] [names...] [options]

Option	Description
`-s, --sandbox`	Apply to sandboxes
`-n, --namespace <ns>`	Namespace to show status for

Examples:

# Show status for all sandboxes
msb server status

# Show status for specific sandboxes
msb server status app database

# Show status for sandboxes in a specific namespace
msb server status --namespace production

# Project Management

Initialize a new microsandbox project.

msb init [--file <path>]

Option	Description
`-f, --file <path>`	Path to the sandbox file or project directory

Examples:

# Initialize project in current directory
msb init


# Initialize project in a specific directory
msb init --file /path/to/project/

# Initialize project with custom sandbox file location
msb init --file ./path/to/Sandboxfile

Add a new sandbox to a project.

msb add [--sandbox] [--build] [--group] <names...> --image <image> [options]

Option	Description
`-s, --sandbox`	Apply to a sandbox (default)
`-b, --build`	Apply to a build sandbox
`-g, --group`	Apply to a group
`--image <image>`	Image to use
`--memory <MiB>`	Memory limit in MiB
`--cpus <count>`	Number of CPUs
`-v, --volume <map>`	Volume mappings (host:container)
`-p, --port <map>`	Port mappings (host:container)
`--env <KEY=VALUE>`	Environment variables
`--env-file <path>`	Environment file
`--depends-on <deps>`	Dependencies
`--workdir <path>`	Working directory
`--shell <shell>`	Shell to use
`--script <name=cmd>`	Scripts to add
`--start <cmd>`	Start script
`--import <name=path>`	Files to import
`--export <name=path>`	Files to export
`--scope <scope>`	Network scope (local/public/any/none)
`-f, --file <path>`	Path to sandbox file

Examples:

# Add a simple sandbox
msb add --sandbox app --image node:18

# Add a simple sandbox (--sandbox is default)
msb add app --image node:18

# Add a sandbox with port mapping and environment variables
msb add web --image nginx:alpine --port 8080:80 --env NODE_ENV=production

# Add a sandbox with volume mounts and resource limits
msb add database --image postgres:15 --volume ./data:/var/lib/postgresql/data --memory 512 --cpus 2

# Add a sandbox with dependencies and custom scripts
msb add api --image my/api --depends-on database --script test="pytest" --start "python app.py"

Remove a sandbox from the project.

msb remove [--sandbox] [--build] [--group] <names...> [--file <path>]

Option	Description
`-s, --sandbox`	Apply to a sandbox (default)
`-b, --build`	Apply to a build sandbox
`-g, --group`	Apply to a group
`-f, --file <path>`	Path to sandbox file

Examples:

# Remove a sandbox
msb remove --sandbox app

# Remove a sandbox (--sandbox is default)
msb remove app

# Remove multiple sandboxes
msb remove web api database

# Remove from a specific sandbox file
msb remove app --file ./path/to/Sandboxfile

List sandboxes defined in a project.

msb list [--sandbox] [--build] [--group] [--file <path>]

Option	Description
`-s, --sandbox`	List sandboxes (default)
`-b, --build`	List build sandboxes
`-g, --group`	List groups
`-f, --file <path>`	Path to sandbox file

Examples:

# List all sandboxes
msb list --sandbox

# List all sandboxes (--sandbox is default)
msb list

# List from a specific sandbox file
msb list --file ./config/sandbox.yaml

# Sandbox Operations

Run a sandbox defined in the project.

msb run [--sandbox] [--build] <NAME[~SCRIPT]> [options] [-- args...]

Option	Description
`-s, --sandbox`	Apply to a sandbox (default)
`-b, --build`	Apply to a build sandbox
`-f, --file <path>`	Path to sandbox file
`-d, --detach`	Run in background
`-e, --exec <cmd>`	Execute a command
`-- <args...>`	Additional arguments

Examples:

# Run a sandbox
msb run --sandbox app

# Run a sandbox (--sandbox is default)
msb run app

# Run a specific script in a sandbox
msb run app~test

# Run a specific script in a sandbox with additional arguments
msb run app~test -- -a 1 -b 2

# Run in background
msb run app --detach

# Execute a command within a sandbox
msb run app --exec bash

# Execute a command within a sandbox with additional arguments
msb run app --exec bash -- -c "echo 'Hello, World!'"

Open a shell in a sandbox. This opens whatever shell is configured for the sandbox image.

msb shell [--sandbox] [--build] <name> [options] [-- args...]

Option	Description
`-s, --sandbox`	Apply to a sandbox (default)
`-b, --build`	Apply to a build sandbox
`-f, --file <path>`	Path to sandbox file
`-d, --detach`	Run in background
`-- <args...>`	Additional arguments

Examples:

# Open shell in a sandbox
msb shell --sandbox app

# Open shell in a sandbox (--sandbox is default)
msb shell app

# Open shell with additional arguments
msb shell app -- -c "echo 'Hello, World!'"

Run a temporary sandbox. This sandbox will be removed after it exits.

msb exe [--image] <NAME[~SCRIPT]> [options] [-- args...]

Option	Description
`--cpus <count>`	Number of CPUs
`--memory <MiB>`	Memory in MB
`-v, --volume <map>`	Volume mappings
`-p, --port <map>`	Port mappings
`--env <KEY=VALUE>`	Environment variables
`--workdir <path>`	Working directory
`--scope <scope>`	Network scope
`-e, --exec <cmd>`	Execute a command
`-- <args...>`	Additional arguments

Examples:

# Run a temporary sandbox with an image (--image is default)
msb exe python:3.11

# Run with resource limits and volume mounts
msb exe ubuntu:22.04 --memory 256 --cpus 1 --volume ./code:/workspace

# Execute a specific command
msb exe node:18 --exec npm -- test

# Run with environment variables and port mapping
msb exe nginx:alpine --env NODE_ENV=production --port 8080:80

# Pass additional arguments
msb exe python:3.11 -- -c "print('Hello World')"

Show logs of a build, sandbox, or group.

msb log [--sandbox] [--build] [--group] <name> [options]

Option	Description
`-s, --sandbox`	Apply to a sandbox (default)
`-b, --build`	Apply to a build sandbox
`-g, --group`	Apply to a group
`-f, --file <path>`	Path to sandbox file
`-f, --follow`	Follow the logs
`-t, --tail <n>`	Number of lines to show

Examples:

# Show logs for a sandbox (--sandbox is default)
msb log app

# Follow logs in real-time
msb log app --follow

# Show last 50 lines
msb log app --tail 50

Show tree of layers that make up a sandbox.

Coming Soon

This will be available in a future release.

msb tree [--sandbox] [--build] [--group] <names...> [-L <level>]

Option	Description
`-s, --sandbox`	Apply to a sandbox (default)
`-b, --build`	Apply to a build sandbox
`-g, --group`	Apply to a group
`-L <level>`	Maximum depth level

Examples:

# Show tree for a sandbox (--sandbox is default)
msb tree app

# Show tree for multiple sandboxes
msb tree app database

# Limit tree depth
msb tree app -L 3

# Project Lifecycle

Start or stop project sandboxes based on configuration.

msb apply [--file <path>] [--detach]

Option	Description
`-f, --file <path>`	Path to sandbox file
`-d, --detach`	Run in background

Examples:

# Apply current project configuration
msb apply

# Apply in background
msb apply --detach

# Apply specific sandbox file
msb apply --file ./path/to/Sandboxfile

Run project sandboxes.

msb up [--sandbox] [--build] [--group] [names...] [options]

Option	Description
`-s, --sandbox`	Apply to sandboxes (default)
`-b, --build`	Apply to build sandboxes
`-g, --group`	Apply to groups
`-f, --file <path>`	Path to sandbox file
`-d, --detach`	Run in background

Examples:

# Start all sandboxes
msb up --sandbox

# Start all sandboxes (--sandbox is default)
msb up

# Start specific sandboxes
msb up app database

# Start in background
msb up --detach

Stop project sandboxes.

msb down [--sandbox] [--build] [--group] [names...] [options]

Option	Description
`-s, --sandbox`	Apply to sandboxes (default)
`-b, --build`	Apply to build sandboxes
`-g, --group`	Apply to groups
`-f, --file <path>`	Path to sandbox file

Examples:

# Stop all sandboxes
msb down --sandbox

# Stop all sandboxes (--sandbox is default)
msb down

# Stop specific sandboxes
msb down app database

# Stop from specific sandbox file
msb down --file ./path/to/Sandboxfile

Show statuses of running sandboxes.

msb status [--sandbox] [--build] [--group] [names...] [options]

Option	Description
`-s, --sandbox`	Apply to sandboxes (default)
`-b, --build`	Apply to build sandboxes
`-g, --group`	Apply to groups
`-f, --file <path>`	Path to sandbox file

Examples:

# Show status of all sandboxes
msb status --sandbox

# Show status of all sandboxes (--sandbox is default)
msb status

# Show status of specific sandboxes
msb status app database

# Show status from specific sandbox file
msb status --file ./path/to/Sandboxfile

# Image Management

Build images.

Coming Soon

This will be available in a future release.

msb build [--build] [--sandbox] [--group] <names...> [--snapshot]

Option	Description
`-b, --build`	Build from build definition
`-s, --sandbox`	Build from sandbox (default)
`-g, --group`	Build from group
`--snapshot`	Create a snapshot

Examples:

# Build from sandbox
msb build app --sandbox

# Build from sandbox (--sandbox is default)
msb build app

# Build multiple sandboxes
msb build app database

# Create a snapshot while building
msb build app --snapshot

Pull image from a registry.

msb pull [--image] [--image-group] <name> [options]

Option	Description
`-i, --image`	Apply to an image (default)
`-G, --image-group`	Apply to an image group
`-L, --layer-path <path>`	Path to store layer files

Examples:

# Pull an image
msb pull --image python:3.11

# Pull an image (--image is default)
msb pull python:3.11

# Pull with custom layer storage path
msb pull ubuntu:22.04 --layer-path /custom/layers

Push image to a registry.

Coming Soon

This will be available in a future release.

msb push [--image] [--image-group] <name>

Option	Description
`-i, --image`	Apply to an image (default)
`-G, --image-group`	Apply to an image group

Examples:

# Push an image
msb push --image myapp:latest

# Push an image (--image is default)
msb push myapp:latest

# Maintenance

Clean cached sandbox layers, metadata, etc.

msb clean [--sandbox] [name] [options]

Option	Description
`-s, --sandbox`	Apply to a sandbox (default)
`-u, --user`	Clean user-level caches
`-a, --all`	Clean all
`-f, --file <path>`	Path to sandbox file
`--force`	Force clean

Examples:

# Clean specific sandbox
msb clean --sandbox app

# Clean specific sandbox (--sandbox is default)
msb clean app

# Clean all caches
msb clean --all

# Clean user-level caches
msb clean --user

# Force clean without confirmation
msb clean app --force

Upgrade microsandbox itself.

Coming Soon

This will be available in a future release.

msb self upgrade

Examples:

# Upgrade to the latest version
msb self upgrade

Uninstall microsandbox.

msb self uninstall

Examples:

# Uninstall microsandbox
msb self uninstall

references