npm package: @stateset/sandbox-cli
Description: CLI for managing StateSet Sandbox environments
Latest version: 1.0.6

# @stateset/sandbox-cli

Command-line interface for managing [StateSet Sandbox](https://github.com/stateset/stateset-sandbox) environments — create sandboxes, manage checkpoints, upload artifacts, orchestrate agent sessions, and more.

## Installation

```bash
npm install -g @stateset/sandbox-cli
```

Requires Node.js >= 20.

## Quick Start

```bash
# Interactive setup — prompts for API key, URL, and defaults
stateset config setup

# Or configure manually
stateset config set-key sk_live_your_api_key
stateset config set-url https://api.stateset.com

# Create a sandbox and run a command
stateset sandbox create --timeout 600
stateset sandbox exec <sandbox-id> "echo hello world"
```

## Configuration

The CLI stores configuration locally via [conf](https://github.com/sindresorhus/conf). Environment variables take precedence over stored values.

| Setting | Env Variable | Default |
|---------|-------------|---------|
| API Key | `STATESET_API_KEY` | — |
| API URL | `STATESET_API_URL` | `http://localhost:8080` |
| Default Timeout | `STATESET_DEFAULT_TIMEOUT_SECONDS` | `300` |

```bash
stateset config show      # Display current configuration
stateset config path      # Show config file location
stateset config clear     # Wipe all stored config
```

## Commands

### `stateset sandbox`

Manage sandbox environments.

```bash
stateset sandbox create [options]       # Create a new sandbox
stateset sandbox list                   # List all sandboxes
stateset sandbox get <id>               # Get sandbox details
stateset sandbox exec <id> <command>    # Execute a command
stateset sandbox stop <id>              # Stop a sandbox
stateset sandbox extend <id>            # Extend sandbox lifetime
stateset sandbox write <id> <path> <content>   # Write a file
stateset sandbox read <id> <path>              # Read a file
stateset sandbox ls-files <id>                 # List directory contents
```

**Create options:**

| Flag | Description | Example |
|------|-------------|---------|
| `-t, --timeout <seconds>` | Sandbox timeout | `--timeout 600` |
| `-c, --cpus <cpus>` | CPU limit | `--cpus 1` |
| `-m, --memory <memory>` | Memory limit | `--memory 1Gi` |
| `-i, --isolation <level>` | Isolation level | `--isolation gvisor` |
| `-e, --env <KEY=VALUE>` | Environment variables (repeatable) | `-e FOO=bar -e BAZ=qux` |

### `stateset checkpoint`

Create, restore, and compare sandbox checkpoints.

```bash
stateset checkpoint create <sandbox-id> <name>    # Create checkpoint
stateset checkpoint list                           # List checkpoints
stateset checkpoint get <id>                       # Get details
stateset checkpoint restore <sandbox-id> <cp-id>   # Restore checkpoint
stateset checkpoint clone <id> <new-name>          # Clone a checkpoint
stateset checkpoint diff <id-1> <id-2>             # Compare two checkpoints
stateset checkpoint rm <id>                        # Delete checkpoint
```

**Create options:** `--description`, `--include <paths>`, `--exclude <paths>`, `--no-env`
**Restore options:** `--no-files`, `--no-env`, `--no-overwrite`

### `stateset artifact`

Upload, download, and manage sandbox artifacts.

```bash
stateset artifact upload <sandbox-id> <path>       # Upload artifact
stateset artifact list                              # List artifacts
stateset artifact get <id>                          # Get details
stateset artifact url <id>                          # Get download URL
stateset artifact download <sandbox-id> <id> <path> # Download artifact
stateset artifact rm <id>                           # Delete artifact
```

**Upload options:** `--type <content-type>`, `--expires <seconds>`, `--metadata <key=value>`

### `stateset session`

Orchestrate long-running agent sessions with budget controls.

```bash
stateset session create [options]         # Create agent session
stateset session list                     # List sessions
stateset session get <id>                 # Get session details
stateset session start <id>              # Start session
stateset session pause <id>              # Pause session
stateset session resume <id>             # Resume session
stateset session stop <id>               # Stop gracefully
stateset session cancel <id>             # Cancel immediately
stateset session exec <id> <command>     # Execute in session
stateset session events <id>             # List session events
```

**Create options:**

| Flag | Description |
|------|-------------|
| `-n, --name <name>` | Session name |
| `-d, --description <desc>` | Description |
| `--cost-cap <cents>` | Cost cap in cents (e.g., 500 = $5) |
| `--iteration-limit <n>` | Max iterations |
| `--duration-limit <seconds>` | Max duration |
| `--cpus <cpus>` | CPU allocation (default: 2) |
| `--memory <memory>` | Memory allocation (default: 4Gi) |

### `stateset tunnel`

Expose sandbox services via tunnels.

```bash
stateset tunnel open <sandbox-id>        # Create tunnel (default port 8080)
stateset tunnel list <sandbox-id>        # List active tunnels
stateset tunnel close <tunnel-id>        # Close tunnel
```

**Open options:** `-p, --port <port>`, `--protocol <http|https>`, `--expires-in <seconds>`

### `stateset pool`

Monitor the warm pod pool.

```bash
stateset pool stats                      # Get pool statistics
stateset pool watch                      # Watch stats in real-time
stateset pool watch --interval 2         # Custom refresh interval
```

### `stateset deploy`

Deploy to Kubernetes via cloud provider overlays.

```bash
stateset deploy aws                      # Deploy AWS overlay
stateset deploy gcp --dry-run            # Dry-run GCP overlay
stateset deploy azure --preflight --wait # Full deploy with checks
```

**Options:** `--kubeconfig`, `--context`, `--namespace`, `--dry-run`, `--preflight`, `--wait`, `--smoke`, `--post-check`

### `stateset doctor`

Diagnose CLI configuration and API connectivity.

```bash
stateset doctor                          # Basic health check
stateset doctor --full                   # Deep diagnostics
stateset doctor --cluster                # Include Kubernetes checks
stateset doctor --api                    # Check dashboard endpoints
```

### `stateset health`

Platform-wide health snapshot.

```bash
stateset health                          # Quick platform status
stateset health --grade                  # Include readiness grade
stateset health --cluster                # Include Kubernetes checks
```

### `stateset grade`

Compute platform readiness grade (A+ through F).

```bash
stateset grade                           # Compute grade
stateset grade --minimum A-              # Fail if below A-
stateset grade --cluster --json          # Full check, JSON output
```

## JSON Output

Most commands support `--json` for machine-readable output, useful for scripting:

```bash
stateset sandbox list --json | jq '.[0].id'
stateset pool stats --json
stateset grade --json
```

## Development

```bash
cd cli
npm install
npm run dev -- sandbox list      # Run locally via tsx
npm run build                    # Compile TypeScript
npm test                         # Run tests
npm run typecheck                # Type-check without emitting
```

## License

MIT