opensandbox-cli 0.1.0.dev1__tar.gz → 0.1.1__tar.gz

{opensandbox_cli-0.1.0.dev1 → opensandbox_cli-0.1.1}/.gitignore

@@ -274,3 +274,5 @@ kubernetes/test/kind/gvisor/runsc
 kubernetes/test/kind/gvisor/containerd-shim-runsc-v1
 bin/
 obj/
+
+.qoder/

{opensandbox_cli-0.1.0.dev1 → opensandbox_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensandbox-cli
-Version: 0.1.0.dev1
+Version: 0.1.1
 Summary: OpenSandbox CLI - Command-line interface for managing sandboxes
 Project-URL: Homepage, https://open-sandbox.ai
 Project-URL: Repository, https://github.com/alibaba/OpenSandbox
@@ -224,7 +224,7 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: click<9.0,>=8.1.0
-Requires-Dist: opensandbox<0.2.0,>=0.1.5
+Requires-Dist: opensandbox<0.2.0,>=0.1.9
 Requires-Dist: pyyaml<7.0,>=6.0
 Requires-Dist: rich<14.0,>=13.0.0
 Requires-Dist: tomli>=2.0.0; python_version < '3.11'
@@ -232,335 +232,358 @@ Description-Content-Type: text/markdown
 
 # OpenSandbox CLI
 
-A command-line interface for managing OpenSandbox environments from your terminal. Built on top of the [OpenSandbox Python SDK](../sdks/sandbox/python/README.md), the CLI provides intuitive commands for sandbox lifecycle management, file operations, command execution, and diagnostics.
+`osb` is the command-line interface for OpenSandbox. It is built for the common day-to-day flows:
 
-## Installation
+- create and manage sandboxes
+- run commands inside a sandbox
+- read and modify sandbox files
+- inspect runtime egress policy
+- collect low-level diagnostics
+- install OpenSandbox-specific skills for coding agents
 
-### pip
+It uses the OpenSandbox Python SDK under the hood and is intended to be the shortest path from a terminal to a working sandbox workflow.
+
+## Install
+
+Choose one:
 
 ```bash
 pip install opensandbox-cli
 ```
 
-### uv
-
 ```bash
 uv tool install opensandbox-cli
 ```
 
-### pipx (recommended for global CLI usage)
-
 ```bash
 pipx install opensandbox-cli
 ```
 
-## Overview
+Confirm the install:
 
 ```bash
 osb --help
+osb --version
 ```
 
-![CLI Help](assets/cli_help.png)
-
-## Quick Start
-
-### Step 0: Start the OpenSandbox Server
+## Before You Start
 
-Before using the CLI, make sure the OpenSandbox server is running. See the root [README.md](../README.md) for startup instructions.
+Make sure an OpenSandbox server is reachable. If you are running locally, start the server first and then point the CLI at it.
 
 ```bash
 opensandbox-server
 ```
 
-![Start OpenSandbox Server](assets/start_opensandbox_server.png)
-
-### Step 1: Install the CLI
-
-```bash
-cd cli
-uv sync
-uv run osb --help
-```
-
-![Install CLI](assets/install_cli.png)
+## Quick Start
 
-### Step 2: Initialize Configuration
+### 1. Initialize config
 
 ```bash
 osb config init
 osb config set connection.domain localhost:8080
 osb config set connection.protocol http
+osb config show -o json
 ```
 
-![Init CLI](assets/init_cli.png)
+If you want a non-default config file, choose it at the root command level for the whole invocation:
+
+```bash
+osb --config /tmp/dev.toml config init
+osb --config /tmp/dev.toml config set connection.domain localhost:8080
+osb --config /tmp/dev.toml config show -o json
+```
 
-### Step 3: Create a Sandbox
+### 2. Create a sandbox
 
 ```bash
-osb sandbox create --image python:3.12
+osb sandbox create --image python:3.12 --timeout 30m -o json
 ```
 
-Or configure defaults once and omit repeated flags:
+If you set defaults first, later create commands can be shorter:
 
 ```bash
 osb config set defaults.image python:3.12
-osb config set defaults.timeout 15m
-osb sandbox create
+osb config set defaults.timeout 30m
+osb sandbox create -o json
 ```
 
-You can also load network policy and volume mounts from JSON files:
+### 3. Verify it is usable
 
 ```bash
-osb sandbox create \
-  --image python:3.12 \
-  --network-policy-file network-policy.json \
-  --volumes-file volumes.json
+osb sandbox get <sandbox-id> -o json
+osb sandbox health <sandbox-id> -o json
 ```
 
-![Create Sandbox](assets/cli_create_sandbox.png)
+### 4. Run a command inside the sandbox
 
-### Step 4: List Sandboxes
+Use `--` before the sandbox command payload.
 
 ```bash
-# Table output (default)
-osb sandbox list
-
-# JSON output for scripting
-osb -o json sandbox list
+osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"
 ```
 
-![List Sandboxes](assets/cli_list_sandbox.png)
-
-![List Sandboxes JSON](assets/cli_list_sandbox_json.png)
+### 5. Read or write a file
 
-### Short ID Matching
+```bash
+osb file write <sandbox-id> /workspace/hello.txt -c "hello" -o json
+osb file cat <sandbox-id> /workspace/hello.txt -o raw
+```
 
-Like Docker, you don't need to type the full sandbox ID — just enough characters to uniquely identify the target sandbox:
+### 6. Clean up
 
 ```bash
-# Full ID
-osb sandbox get db027570-4f86-45f8-b1a8-c31a2dd90da8
-
-# Short prefix — as long as it's unambiguous
-osb sandbox get db02
-osb exec db02 -- echo "hello"
+osb sandbox kill <sandbox-id> -o json
 ```
 
-If the prefix matches multiple sandboxes, the CLI will report an error listing the matches so you can be more specific.
+## Common Tasks
 
-![Short ID Matching](assets/cli_sandbox_search.png)
+### Create sandboxes
 
-### Step 5: Execute Commands
+Basic:
 
 ```bash
-osb exec <sandbox-id> -- echo "hello world"
-osb exec <sandbox-id> -- python -c "print(1+1)"
+osb sandbox create --image python:3.12
 ```
 
-![Execute Commands](assets/cli_sandbox_exec.png)
+Private image:
 
-### Step 6: File Operations
+```bash
+osb sandbox create \
+  --image my-registry.example.com/team/app:latest \
+  --image-auth-username alice \
+  --image-auth-password <token>
+```
+
+Manual cleanup mode:
 
 ```bash
-# Write a file
-osb file write <sandbox-id> /tmp/test.txt -c "hello"
+osb sandbox create --image python:3.12 --timeout none
+```
+
+Explicit entrypoint argv:
 
-# Read it back
-osb file cat <sandbox-id> /tmp/test.txt
+```bash
+osb sandbox create \
+  --image python:3.12 \
+  --entrypoint python \
+  --entrypoint -m \
+  --entrypoint http.server
 ```
 
-![File Operations](assets/cli_sandbox_file.png)
+Create with network policy and volumes:
+
+```bash
+osb sandbox create \
+  --image python:3.12 \
+  --network-policy-file network-policy.json \
+  --volumes-file volumes.json
+```
 
-### Step 7: Cleanup
+### List and inspect sandboxes
 
 ```bash
-osb sandbox kill <sandbox-id>
 osb sandbox list
+osb sandbox list -o json
+osb sandbox list --state running --state paused
+osb sandbox get <sandbox-id> -o json
+osb sandbox metrics <sandbox-id>
+osb sandbox metrics <sandbox-id> --watch -o raw
 ```
 
-![Kill Sandbox](assets/cli_kill_sandbox.png)
+### Expose a service
 
-## Command Reference
-
-### `osb sandbox` — Lifecycle Management
+```bash
+osb sandbox endpoint <sandbox-id> --port 8080 -o json
+```
 
-| Command    | Description                                 |
-| ---------- | ------------------------------------------- |
-| `create`   | Create a new sandbox                        |
-| `list`     | List sandboxes (with optional filters)      |
-| `get`      | Get sandbox details by ID                   |
-| `kill`     | Terminate one or more sandboxes             |
-| `pause`    | Pause a running sandbox                     |
-| `resume`   | Resume a paused sandbox                     |
-| `renew`    | Renew sandbox expiration                    |
-| `endpoint` | Get public endpoint for a sandbox port      |
-| `health`   | Check sandbox health                        |
-| `metrics`  | Get sandbox resource metrics (CPU, memory)  |
+### Run commands
 
-### `osb command` — Command Execution
+Foreground streaming:
 
-| Command     | Description                               |
-| ----------- | ----------------------------------------- |
-| `run`       | Run a shell command in the sandbox        |
-| `status`    | Get command execution status              |
-| `logs`      | Get background command logs               |
-| `interrupt` | Interrupt a running command               |
-| `session`   | Manage persistent bash sessions           |
+```bash
+osb command run <sandbox-id> -o raw -- sh -lc 'echo ready'
+```
 
-### `osb exec` — Quick Command Shortcut
+Tracked background execution:
 
 ```bash
-osb exec <sandbox-id> -- <command>
+osb command run <sandbox-id> --background -o json -- sh -c "sleep 10; echo done"
+osb command status <sandbox-id> <execution-id> -o json
+osb command logs <sandbox-id> <execution-id> -o json
 ```
 
-Shortcut for `osb command run`. Everything after `--` is passed as the command.
-
-Persistent shell sessions:
+Persistent shell session:
 
 ```bash
-# Create a bash session
-osb command session create <sandbox-id>
+osb command session create <sandbox-id> --workdir /workspace -o json
+osb command session run <sandbox-id> <session-id> -o raw -- pwd
+osb command session run <sandbox-id> <session-id> -o raw -- export FOO=bar
+osb command session run <sandbox-id> <session-id> -o raw -- sh -c 'echo $FOO'
+osb command session delete <sandbox-id> <session-id> -o json
+```
 
-# Reuse that session for multiple commands
-osb command session run <sandbox-id> <session-id> -- pwd
-osb command session run <sandbox-id> <session-id> -- export FOO=bar
-osb command session run <sandbox-id> <session-id> -- sh -c 'echo $FOO'
+### Work with files
 
-# Delete the session when done
-osb command session delete <sandbox-id> <session-id>
+```bash
+osb file upload <sandbox-id> ./local.txt /workspace/local.txt -o json
+osb file download <sandbox-id> /workspace/result.json ./result.json -o json
+osb file search <sandbox-id> /workspace --pattern "*.py" -o json
+osb file info <sandbox-id> /workspace/main.py -o json
+osb file replace <sandbox-id> /workspace/app.py --old old --new new -o json
+osb file chmod <sandbox-id> /workspace/script.sh --mode 755 -o json
 ```
 
-### `osb file` — File Operations
+### Manage runtime egress policy
 
-| Command    | Description                                |
-| ---------- | ------------------------------------------ |
-| `cat`      | Read file contents                         |
-| `write`    | Write content to a file                    |
-| `upload`   | Upload a local file to the sandbox         |
-| `download` | Download a file from the sandbox           |
-| `rm`       | Delete files                               |
-| `mv`       | Move or rename a file                      |
-| `mkdir`    | Create directories                         |
-| `rmdir`    | Remove directories                         |
-| `search`   | Search for files by pattern                |
-| `info`     | Get file/directory metadata                |
-| `chmod`    | Set file permissions                       |
-| `replace`  | Find and replace content in a file         |
+Inspect current policy:
 
-### `osb egress` — Runtime Egress Policy
+```bash
+osb egress get <sandbox-id> -o json
+```
 
-| Command | Description                              |
-| ------- | ---------------------------------------- |
-| `get`   | Get the current runtime egress policy    |
-| `patch` | Patch runtime egress rules with merge semantics |
+Patch specific rules:
 
 ```bash
-# Inspect current policy
-osb egress get <sandbox-id>
+osb egress patch <sandbox-id> --rule allow=pypi.org --rule deny=internal.example.com -o json
+```
+
+If you are debugging connectivity, verify behavior with an actual command:
 
-# Allow PyPI and deny an internal domain
-osb egress patch <sandbox-id> --rule allow=pypi.org --rule deny=internal.example.com
+```bash
+osb command run <sandbox-id> -o raw -- curl -I https://pypi.org
 ```
 
-### `osb devops` — Experimental DevOps Diagnostics
+### Collect diagnostics
 
-| Command   | Description                                          |
-| --------- | ---------------------------------------------------- |
-| `logs`    | Retrieve container/pod logs                          |
-| `inspect` | Retrieve detailed container/pod inspection info      |
-| `events`  | Retrieve events related to a sandbox                 |
-| `summary` | One-shot diagnostics: inspect + events + logs combined |
+Use the stable diagnostics commands for API-backed log and event descriptors.
+
+```bash
+osb diagnostics events <sandbox-id> --scope lifecycle -o raw
+osb diagnostics events <sandbox-id> --scope runtime -o raw
+osb diagnostics logs <sandbox-id> --scope container -o raw
+osb diagnostics logs <sandbox-id> --scope lifecycle -o json
+osb diagnostics events <sandbox-id> --scope runtime -o json
+osb diagnostics logs <sandbox-id> --scope container -o yaml
+```
 
-These diagnostics commands are currently experimental. They are implemented by the server and exposed by the CLI, but are not yet part of the public `specs/` API contract and may change before being formalized.
+`--scope` is required for stable diagnostics. Common scopes are `lifecycle` and
+`container` for logs, and `lifecycle` and `runtime` for events. Raw output
+prints inline diagnostic text, or the content URL when diagnostics are
+delivered as a temporary URL. Structured CLI output follows the SDK/Python field
+style, for example `content_url`, `content_length`, and `expires_at`.
+Some server builds may return `DIAGNOSTICS_NOT_IMPLEMENTED` for scoped
+diagnostics until the stable backend implementation is enabled.
+
+Legacy DevOps diagnostics remain experimental. Prefer `osb diagnostics logs/events`
+for stable API-backed log and event collection.
 
 ```bash
-# Quick diagnostics summary
-osb devops summary <sandbox-id>
+osb devops inspect <sandbox-id> -o raw
+osb devops summary <sandbox-id> -o raw
+```
+
+## Output Formats
 
-# Get last 500 log lines
-osb devops logs <sandbox-id> --tail 500
+Output selection is command-scoped, not global.
 
-# Get logs from the last 30 minutes
-osb devops logs <sandbox-id> --since 30m
+- `table`: human-readable tables and panels
+- `json`: machine-readable JSON
+- `yaml`: machine-readable YAML
+- `raw`: unformatted text or streaming output
 
-# Detailed container/pod inspection
-osb devops inspect <sandbox-id>
+Examples:
 
-# View events (up to 100)
-osb devops events <sandbox-id> --limit 100
+```bash
+osb sandbox list -o json
+osb sandbox list -o yaml
+osb file cat <sandbox-id> /workspace/hello.txt -o raw
 ```
 
-All devops commands return plain text output, making them ideal for both human reading and AI agent consumption.
+Not every command supports every format. Use `--help` on the specific command when in doubt.
+
+## Command Groups
 
-![DevOps Summary 1](assets/cli_devops_summary_1.png)
+The main command groups are:
 
-![DevOps Summary 2](assets/cli_devops_summary_2.png)
+- `osb sandbox`: lifecycle management
+- `osb command`: command execution and persistent sessions
+- `osb file`: file and directory operations
+- `osb egress`: runtime egress policy
+- `osb diagnostics`: stable diagnostics logs and events
+- `osb devops`: experimental legacy diagnostics
+- `osb config`: local CLI configuration
+- `osb skills`: bundled skills for AI tools
 
-### `osb skills` — AI Coding Skills
+Explore them directly:
 
-| Command     | Description                                          |
-| ----------- | ---------------------------------------------------- |
-| `install`   | Install OpenSandbox troubleshooting skill for AI tools |
-| `list`      | List supported targets and their install status      |
-| `uninstall` | Remove installed skill from AI tools                 |
+```bash
+osb sandbox --help
+osb command --help
+osb file --help
+osb skills --help
+```
 
-The troubleshooting skill enables AI coding assistants to automatically diagnose sandbox issues (OOM, crashes, image pull errors, etc.). Supported targets:
+## Agent Skills
 
-| Target    | AI Tool          | Install Location |
-| --------- | ---------------- | ---------------- |
-| `claude`  | Claude Code      | `~/.claude/skills/` |
-| `cursor`  | Cursor           | `~/.cursor/rules/` |
-| `codex`   | Codex            | `~/.codex/instructions.md` |
-| `copilot` | GitHub Copilot   | `~/.github/copilot-instructions.md` |
-| `windsurf`| Windsurf         | `~/.windsurfrules` |
-| `cline`   | Cline            | `~/.clinerules` |
+The CLI ships with built-in OpenSandbox skills for coding agents and agent-oriented tools.
 
-```bash
-# Install for Claude Code (default)
-osb skills install
+Bundled skills:
 
-# Install for a specific tool
-osb skills install --target cursor
+- `sandbox-lifecycle`
+- `command-execution`
+- `file-operations`
+- `network-egress`
+- `sandbox-troubleshooting`
 
-# Install for all supported tools
-osb skills install --target all
+Supported targets:
 
-# Check install status
-osb skills list
+| Target | Install location |
+| --- | --- |
+| `claude` | `./.claude/skills/` or `~/.claude/skills/` |
+| `cursor` | `./.cursor/rules/` or `~/.cursor/rules/` |
+| `codex` | `./.codex/skills/<name>/SKILL.md` or `~/.codex/skills/<name>/SKILL.md` |
+| `copilot` | `./.github/copilot-instructions.md` or `~/.github/copilot-instructions.md` |
+| `windsurf` | `./.windsurfrules` or `~/.windsurfrules` |
+| `cline` | `./.clinerules` or `~/.clinerules` |
+| `opencode` | `./.agents/skills/<name>/SKILL.md` or `~/.agents/skills/<name>/SKILL.md` |
 
-# Uninstall
-osb skills uninstall --target claude
-```
+Common flows:
 
-### `osb config` — Configuration
+```bash
+osb skills list
+osb skills show sandbox-lifecycle
+osb skills install sandbox-lifecycle --target codex --scope project
+osb skills install --all-builtins --target codex --scope global
+osb skills uninstall sandbox-troubleshooting --target claude --scope global
+```
 
-| Command | Description                                |
-| ------- | ------------------------------------------ |
-| `init`  | Create a default config file               |
-| `show`  | Show resolved configuration                |
+For scripts or agents, use structured output:
 
-## Configuration
+```bash
+osb skills install sandbox-lifecycle --target codex --scope project -o json
+```
 
-The CLI resolves configuration from multiple sources with the following priority (highest to lowest):
+## Configuration Model
 
-1. **CLI flags** — `--api-key`, `--domain`, `--protocol`, `--timeout`
-2. **Environment variables** — `OPEN_SANDBOX_API_KEY`, `OPEN_SANDBOX_DOMAIN`, `OPEN_SANDBOX_PROTOCOL`, `OPEN_SANDBOX_REQUEST_TIMEOUT`, `OPEN_SANDBOX_OUTPUT`
-3. **Config file** — `~/.opensandbox/config.toml` (or path specified via `--config`)
-4. **SDK defaults**
+The CLI resolves configuration in this order:
 
-## Development
+1. root CLI flags such as `--api-key`, `--domain`, `--protocol`, `--request-timeout`, `--config`
+2. environment variables such as `OPEN_SANDBOX_API_KEY` and `OPEN_SANDBOX_DOMAIN`
+3. config file, defaulting to `~/.opensandbox/config.toml`
+4. SDK defaults
 
-For local CLI development in this monorepo, prefer `uv sync` from the `cli/` directory. That workflow honors the local `[tool.uv.sources]` override for `opensandbox`, so the CLI resolves against the checked-out SDK instead of the published package.
+Config commands:
 
 ```bash
-cd cli
-uv sync
-uv run osb --help
+osb config init
+osb config show
+osb config set connection.domain localhost:8080
+osb config set connection.protocol http
+osb config set defaults.image python:3.12
+osb config set defaults.timeout 30m
 ```
 
-If you specifically need an editable install into another environment, install the SDK dependencies from their local paths first, then install the CLI.
-
-### Config File Format
+Example config file:
 
 ```toml
 [connection]
@@ -568,45 +591,25 @@ api_key = "your-api-key"
 domain = "localhost:8080"
 protocol = "http"
 request_timeout = 30
+use_server_proxy = false
 
 [output]
-format = "table"    # table | json | yaml
 color = true
 
 [defaults]
-image = "python:3.11"
-timeout = "10m"
+image = "python:3.12"
+timeout = "30m"
 ```
 
-## Global Options
-
-| Option                        | Description                      |
-| ----------------------------- | -------------------------------- |
-| `--api-key TEXT`              | API key for authentication       |
-| `--domain TEXT`               | API server domain                |
-| `--protocol [http\|https]`    | Protocol                         |
-| `--timeout INTEGER`           | Request timeout in seconds       |
-| `-o, --output [table\|json\|yaml]` | Output format              |
-| `--config PATH`               | Config file path                 |
-| `-v, --verbose`               | Enable debug output              |
-| `--no-color`                  | Disable colored output           |
-| `--version`                   | Show version                     |
-
-## Output Formats
-
-The CLI supports three output formats via the `-o` / `--output` flag:
+## Development
 
-- **`table`** (default) — Human-friendly tables powered by [Rich](https://github.com/Textualize/rich)
-- **`json`** — Machine-readable JSON
-- **`yaml`** — YAML output
+For local development in this monorepo:
 
 ```bash
-# Table (default)
-osb sandbox list
-
-# JSON for scripting
-osb -o json sandbox list
-
-# YAML
-osb -o yaml sandbox list
+cd cli
+uv sync
+uv run osb --help
+uv run pytest
 ```
+
+This repository uses a local `uv` source override for the OpenSandbox Python SDK, so running from `cli/` will resolve against the checked-out SDK in the monorepo.