docs: Add CLI quickstart guide

Add docs/guides/cli.md covering installation, common workflows
(ls, exec, logs, shell), and JSON output for scripting with jq.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Author: iiilisan

docs/guides/AGENTS.md

@@ -6,6 +6,7 @@ Task-oriented guides for common operations. Each guide answers "How do I...?"
 
 | Guide | Task |
 |-------|------|
+| `cli.md` | CLI install, common workflows (ls, exec, logs, shell), JSON scripting |
 | `sandbox-lifecycle.md` | Understand sandbox states, creation, starting, waiting, and stopping |
 | `execution.md` | Run commands with `exec()` - buffered and streaming modes |
 | `file-operations.md` | Read and write files in sandboxes |

docs/guides/cli.md

@@ -0,0 +1,93 @@
+<!--
+SPDX-FileCopyrightText: 2025 CoreWeave, Inc.
+SPDX-License-Identifier: Apache-2.0
+SPDX-PackageName: aviato-client
+-->
+
+# CLI Quickstart
+
+The `aviato` CLI provides terminal access to sandbox management. All commands wrap the Python SDK.
+
+## Installation
+
+```bash
+pip install aviato[cli]
+```
+
+Or with uv in a development checkout:
+
+```bash
+uv sync --extra cli
+```
+
+Verify the installation:
+
+```bash
+aviato --version
+aviato --help
+```
+
+## Common workflows
+
+### List and inspect sandboxes
+
+```bash
+aviato ls                                      # All sandboxes
+aviato ls --status running                     # Filter by status
+aviato ls --tag my-project                     # Filter by tag
+aviato ls --runway-id default --tower-id t1    # Filter by infrastructure
+```
+
+### Run a command
+
+```bash
+aviato exec <sandbox-id> echo hello
+aviato exec <sandbox-id> --cwd /app python main.py
+aviato exec <sandbox-id> --timeout 30 make test
+```
+
+The exit code matches the remote command's exit code.
+
+### Stream logs
+
+```bash
+aviato logs <sandbox-id>                       # Recent logs
+aviato logs <sandbox-id> --follow              # Continuous (like tail -f)
+aviato logs <sandbox-id> --tail 50 --timestamps
+```
+
+### Interactive shell
+
+```bash
+aviato shell <sandbox-id>                      # Bash shell
+aviato shell <sandbox-id> --cmd /bin/zsh       # Custom shell
+aviato shell <sandbox-id> --cmd "python main.py"
+```
+
+Exit with Ctrl-D or `exit`. Unix only.
+
+## JSON output for scripting
+
+`aviato ls -o json` returns a JSON array for use with `jq`:
+
+```bash
+# List as JSON
+aviato ls -o json
+
+# Get sandbox IDs
+aviato ls -o json | jq -r '.[].sandbox_id'
+
+# Exec into each running sandbox
+aviato ls -o json | jq -r '.[].sandbox_id' | xargs -I{} aviato exec {} echo hello
+
+# Filter by field
+aviato ls -o json | jq '.[] | select(.tower_id == "my-tower")'
+```
+
+Each object contains: `sandbox_id`, `status`, `tower_id`, `runway_id`, `tower_group_id`, `started_at` (ISO 8601 or null).
+
+## See also
+
+- [Command Execution](execution.md) — `exec()` SDK method details
+- [Sandbox Logging](logging.md) — `stream_logs()` SDK method details
+- [Interactive Shells](interactive-shells.md) — `shell()` SDK method details

mkdocs.yml

@@ -75,6 +75,7 @@ nav:
       - 7. Remote Function Execution: tutorial/07-remote-functions.md
       - 8. Cleanup: tutorial/08-cleanup.md
   - Guides:
+      - CLI Quickstart: guides/cli.md
       - Sandbox Lifecycle: guides/sandbox-lifecycle.md
       - Command Execution: guides/execution.md
       - Interactive Shells: guides/interactive-shells.md