@stateset/sandbox-cli 1.0.5 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +221 -0
  2. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,221 @@
1
+ # @stateset/sandbox-cli
2
+
3
+ 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.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install -g @stateset/sandbox-cli
9
+ ```
10
+
11
+ Requires Node.js >= 20.
12
+
13
+ ## Quick Start
14
+
15
+ ```bash
16
+ # Interactive setup — prompts for API key, URL, and defaults
17
+ stateset config setup
18
+
19
+ # Or configure manually
20
+ stateset config set-key sk_live_your_api_key
21
+ stateset config set-url https://api.stateset.com
22
+
23
+ # Create a sandbox and run a command
24
+ stateset sandbox create --timeout 600
25
+ stateset sandbox exec <sandbox-id> "echo hello world"
26
+ ```
27
+
28
+ ## Configuration
29
+
30
+ The CLI stores configuration locally via [conf](https://github.com/sindresorhus/conf). Environment variables take precedence over stored values.
31
+
32
+ | Setting | Env Variable | Default |
33
+ |---------|-------------|---------|
34
+ | API Key | `STATESET_API_KEY` | — |
35
+ | API URL | `STATESET_API_URL` | `http://localhost:8080` |
36
+ | Default Timeout | `STATESET_DEFAULT_TIMEOUT_SECONDS` | `300` |
37
+
38
+ ```bash
39
+ stateset config show # Display current configuration
40
+ stateset config path # Show config file location
41
+ stateset config clear # Wipe all stored config
42
+ ```
43
+
44
+ ## Commands
45
+
46
+ ### `stateset sandbox`
47
+
48
+ Manage sandbox environments.
49
+
50
+ ```bash
51
+ stateset sandbox create [options] # Create a new sandbox
52
+ stateset sandbox list # List all sandboxes
53
+ stateset sandbox get <id> # Get sandbox details
54
+ stateset sandbox exec <id> <command> # Execute a command
55
+ stateset sandbox stop <id> # Stop a sandbox
56
+ stateset sandbox extend <id> # Extend sandbox lifetime
57
+ stateset sandbox write <id> <path> <content> # Write a file
58
+ stateset sandbox read <id> <path> # Read a file
59
+ stateset sandbox ls-files <id> # List directory contents
60
+ ```
61
+
62
+ **Create options:**
63
+
64
+ | Flag | Description | Example |
65
+ |------|-------------|---------|
66
+ | `-t, --timeout <seconds>` | Sandbox timeout | `--timeout 600` |
67
+ | `-c, --cpus <cpus>` | CPU limit | `--cpus 1` |
68
+ | `-m, --memory <memory>` | Memory limit | `--memory 1Gi` |
69
+ | `-i, --isolation <level>` | Isolation level | `--isolation gvisor` |
70
+ | `-e, --env <KEY=VALUE>` | Environment variables (repeatable) | `-e FOO=bar -e BAZ=qux` |
71
+
72
+ ### `stateset checkpoint`
73
+
74
+ Create, restore, and compare sandbox checkpoints.
75
+
76
+ ```bash
77
+ stateset checkpoint create <sandbox-id> <name> # Create checkpoint
78
+ stateset checkpoint list # List checkpoints
79
+ stateset checkpoint get <id> # Get details
80
+ stateset checkpoint restore <sandbox-id> <cp-id> # Restore checkpoint
81
+ stateset checkpoint clone <id> <new-name> # Clone a checkpoint
82
+ stateset checkpoint diff <id-1> <id-2> # Compare two checkpoints
83
+ stateset checkpoint rm <id> # Delete checkpoint
84
+ ```
85
+
86
+ **Create options:** `--description`, `--include <paths>`, `--exclude <paths>`, `--no-env`
87
+ **Restore options:** `--no-files`, `--no-env`, `--no-overwrite`
88
+
89
+ ### `stateset artifact`
90
+
91
+ Upload, download, and manage sandbox artifacts.
92
+
93
+ ```bash
94
+ stateset artifact upload <sandbox-id> <path> # Upload artifact
95
+ stateset artifact list # List artifacts
96
+ stateset artifact get <id> # Get details
97
+ stateset artifact url <id> # Get download URL
98
+ stateset artifact download <sandbox-id> <id> <path> # Download artifact
99
+ stateset artifact rm <id> # Delete artifact
100
+ ```
101
+
102
+ **Upload options:** `--type <content-type>`, `--expires <seconds>`, `--metadata <key=value>`
103
+
104
+ ### `stateset session`
105
+
106
+ Orchestrate long-running agent sessions with budget controls.
107
+
108
+ ```bash
109
+ stateset session create [options] # Create agent session
110
+ stateset session list # List sessions
111
+ stateset session get <id> # Get session details
112
+ stateset session start <id> # Start session
113
+ stateset session pause <id> # Pause session
114
+ stateset session resume <id> # Resume session
115
+ stateset session stop <id> # Stop gracefully
116
+ stateset session cancel <id> # Cancel immediately
117
+ stateset session exec <id> <command> # Execute in session
118
+ stateset session events <id> # List session events
119
+ ```
120
+
121
+ **Create options:**
122
+
123
+ | Flag | Description |
124
+ |------|-------------|
125
+ | `-n, --name <name>` | Session name |
126
+ | `-d, --description <desc>` | Description |
127
+ | `--cost-cap <cents>` | Cost cap in cents (e.g., 500 = $5) |
128
+ | `--iteration-limit <n>` | Max iterations |
129
+ | `--duration-limit <seconds>` | Max duration |
130
+ | `--cpus <cpus>` | CPU allocation (default: 2) |
131
+ | `--memory <memory>` | Memory allocation (default: 4Gi) |
132
+
133
+ ### `stateset tunnel`
134
+
135
+ Expose sandbox services via tunnels.
136
+
137
+ ```bash
138
+ stateset tunnel open <sandbox-id> # Create tunnel (default port 8080)
139
+ stateset tunnel list <sandbox-id> # List active tunnels
140
+ stateset tunnel close <tunnel-id> # Close tunnel
141
+ ```
142
+
143
+ **Open options:** `-p, --port <port>`, `--protocol <http|https>`, `--expires-in <seconds>`
144
+
145
+ ### `stateset pool`
146
+
147
+ Monitor the warm pod pool.
148
+
149
+ ```bash
150
+ stateset pool stats # Get pool statistics
151
+ stateset pool watch # Watch stats in real-time
152
+ stateset pool watch --interval 2 # Custom refresh interval
153
+ ```
154
+
155
+ ### `stateset deploy`
156
+
157
+ Deploy to Kubernetes via cloud provider overlays.
158
+
159
+ ```bash
160
+ stateset deploy aws # Deploy AWS overlay
161
+ stateset deploy gcp --dry-run # Dry-run GCP overlay
162
+ stateset deploy azure --preflight --wait # Full deploy with checks
163
+ ```
164
+
165
+ **Options:** `--kubeconfig`, `--context`, `--namespace`, `--dry-run`, `--preflight`, `--wait`, `--smoke`, `--post-check`
166
+
167
+ ### `stateset doctor`
168
+
169
+ Diagnose CLI configuration and API connectivity.
170
+
171
+ ```bash
172
+ stateset doctor # Basic health check
173
+ stateset doctor --full # Deep diagnostics
174
+ stateset doctor --cluster # Include Kubernetes checks
175
+ stateset doctor --api # Check dashboard endpoints
176
+ ```
177
+
178
+ ### `stateset health`
179
+
180
+ Platform-wide health snapshot.
181
+
182
+ ```bash
183
+ stateset health # Quick platform status
184
+ stateset health --grade # Include readiness grade
185
+ stateset health --cluster # Include Kubernetes checks
186
+ ```
187
+
188
+ ### `stateset grade`
189
+
190
+ Compute platform readiness grade (A+ through F).
191
+
192
+ ```bash
193
+ stateset grade # Compute grade
194
+ stateset grade --minimum A- # Fail if below A-
195
+ stateset grade --cluster --json # Full check, JSON output
196
+ ```
197
+
198
+ ## JSON Output
199
+
200
+ Most commands support `--json` for machine-readable output, useful for scripting:
201
+
202
+ ```bash
203
+ stateset sandbox list --json | jq '.[0].id'
204
+ stateset pool stats --json
205
+ stateset grade --json
206
+ ```
207
+
208
+ ## Development
209
+
210
+ ```bash
211
+ cd cli
212
+ npm install
213
+ npm run dev -- sandbox list # Run locally via tsx
214
+ npm run build # Compile TypeScript
215
+ npm test # Run tests
216
+ npm run typecheck # Type-check without emitting
217
+ ```
218
+
219
+ ## License
220
+
221
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@stateset/sandbox-cli",
3
- "version": "1.0.5",
3
+ "version": "1.0.6",
4
4
  "description": "CLI for managing StateSet Sandbox environments",
5
5
  "type": "module",
6
6
  "bin": {