@tangle-network/sandbox-cli 0.2.9 → 0.2.11

package/SKILL.md

@@ -1,88 +1,308 @@
-# Tangle Hub CLI
+---
+name: tangle-cli
+description: Use when interacting with Tangle sandboxes, executing hub tools, managing agent tasks, operating on sandbox filesystems, building workflows, connecting to external providers, or setting up integrations and automations from a terminal. Triggers include tangle, tangle sandbox, tangle hub, tangle agent, tangle exec, tangle fs, tangle snapshot, tangle secret, tangle workflows, tangle hub connect, github, slack, google, microsoft, external connections, provider integrations, hub tools, or any tangle command.
+---
 
-Use this skill when an agent needs to discover or run Tangle Hub tools from a sandbox or local terminal.
+# Tangle CLI
 
-## Purpose
+## Overview
 
-Tangle Hub lets agents use connected provider tools through Tangle, without seeing provider OAuth tokens. MVP focuses on personal GitHub connections and read-only GitHub issue/PR tools.
+`tangle` is the CLI for Tangle Sandbox operations — create sandboxes, run agents, execute hub tools, manage files, secrets, snapshots, git, and more. All commands support `--help` for inline reference.
 
 ## Auth
 
-Use one auth mode:
+Generic command auth modes, resolved in order:
 
-- Existing CLI auth from `tangle auth login` or saved profile.
-- `TANGLE_API_KEY` for API-key auth.
-- `TANGLE_HUB_CAPABILITY_TOKEN` for scoped sandbox/runtime execution.
+| Priority | Source | Set via |
+|----------|--------|--------|
+| 1 | CLI flag | `--api-key <key>` |
+| 2 | Env var | `TANGLE_API_KEY` or `SANDBOX_API_KEY` |
+| 3 | Profile store | `tangle auth login` (keychain or file) |
 
-Never print provider tokens, API keys, OAuth codes, refresh tokens, client secrets, or capability tokens.
+Hub commands resolve auth in this order:
 
-## Workflow
+| Priority | Source | Set via |
+|----------|--------|--------|
+| 1 | CLI flag | `--api-key <key>` |
+| 2 | Hub capability | `TANGLE_HUB_CAPABILITY_TOKEN` |
+| 3 | Env var | `TANGLE_API_KEY` or `SANDBOX_API_KEY` |
+| 4 | Profile store | `tangle auth login` (keychain or file) |
 
-1. Check auth and provider readiness:
+**Inside a sandbox:** `tangle` is automatically authenticated. No extra auth needed — commands work out of the box.
 
 ```bash
-tangle hub status --json
+# Browser login (preferred)
+tangle auth login
+
+# Device-code login (headless)
+tangle auth login --no-browser
+
+# API key directly
+tangle auth login --api-key sk-tan-...
+
+# Check auth state
+tangle auth status --json
+
+# Named profiles for multiple accounts
+tangle auth login --profile work
+tangle auth profiles use work
 ```
 
-2. Connect GitHub when no connection exists:
+For hub env auth, set **exactly one** of `TANGLE_API_KEY`/`SANDBOX_API_KEY` or `TANGLE_HUB_CAPABILITY_TOKEN`.
+
+## Sandbox Lifecycle
 
 ```bash
-tangle hub connect github
+# Create sandboxes
+tangle sandbox create --name my-project
+tangle sandbox create --name demo --template node-ts
+tangle sandbox list
+tangle sandbox get <id>
+tangle sandbox stop <id>
+tangle sandbox resume <id>
+tangle sandbox delete <id>
+
+# Network
+tangle sandbox expose <id> --port 3000
+tangle sandbox urls <id>
 ```
 
-3. List sources and search tools:
+## Hub — Full Workflow
+
+Hub lets agents use connected provider tools (GitHub, etc.) through Tangle without seeing provider OAuth tokens.
+
+### Auth Check & Connection
 
 ```bash
-tangle hub tools sources --json
-tangle hub tools search github issues --provider github --json
+# Check status first
+tangle hub status --json
+
+# Connect GitHub when no connection exists
+tangle hub connect github
+tangle hub connect github --no-browser  # print URL instead of opening
+
+# List connections
+tangle hub connections --json
+tangle hub connections revoke conn_xxx --force
 ```
 
-4. Describe a tool before calling it:
+### Tool Discovery
+
+Always follow: **sources → search → describe → call**
 
 ```bash
+# List available tool sources (providers)
+tangle hub tools sources --json
+
+# Search for tools
+tangle hub tools search "github issues" --provider github --json
+
+# Describe a tool to see input/output schemas
 tangle hub tools describe github.issues.listIssues --json
 ```
 
-5. Call tools with JSON input:
+### Tool Execution
+
+Two equivalent commands — `call` and `exec`:
 
 ```bash
+# Basic call: <path tokens...> <json-input>
 tangle hub call github issues listIssues '{"owner":"tangle-network","repo":"agent-dev-container"}'
 tangle hub exec github.issues.listIssues '{"owner":"tangle-network","repo":"agent-dev-container"}'
+
+# With explicit connection
+tangle hub call github issues createIssue '{"owner":"foo","repo":"bar","title":"Fix bug"}' --connection conn_xxx
 ```
 
-For policy-gated tools, approve and retry in one command:
+### Policy & Approvals
+
+Tools default to `ask` policy — they pause and require approval on first use.
 
 ```bash
-tangle hub exec github.issues.create '{"owner":"tangle-network","repo":"agent-dev-container","title":"Bug"}' --approve
+# List pending approvals
+tangle hub approvals list
+tangle hub approvals approve <approval-id>
+tangle hub approvals deny <approval-id>
+
+# Set policy to always allow (skip future approvals)
+tangle hub permissions set --connection conn_xxx --action github.issues.listIssues --decision allow
+
+# Set policy to always deny (block tool)
+tangle hub permissions set --connection conn_xxx --action github.issues.deleteIssue --decision deny
+
+# View current policies
+tangle hub permissions list --connection conn_xxx
 ```
 
-Prefer `--json` for machine parsing where commands support it.
+### Auto-Approve Execution
 
-## Connections
+When you expect `HUB_APPROVAL_REQUIRED`, approve and retry in one command:
 
-List and revoke connections:
+```bash
+tangle hub exec github.issues.create '{"owner":"foo","repo":"bar","title":"Bug"}' --approve
+```
+
+### Resume a Paused Execution
+
+When an execution is paused by approval (inside a sandbox), resolve it:
 
 ```bash
-tangle hub connections --json
-tangle hub connections revoke conn_example --force
+tangle hub resume <approval-id> --accept   # approve and mint capability token
+tangle hub resume <approval-id> --decline  # deny
+#Then rerun original exec with --approve
+```
+
+### GitHub App (repo-scoped token mint)
+
+```bash
+# Mint a short-lived repo-scoped installation token (via hub)
+tangle hub github-app mint-installation-token --repo-url https://github.com/owner/repo
 ```
 
-## Approvals And Resume
+## Secrets
 
-`HUB_APPROVAL_REQUIRED` pauses an executor call and returns an approval object in the response details. Use approvals commands to inspect or resolve it:
+Secrets are scoped to your account (or team). Use `--reveal` to see values.
 
 ```bash
-tangle hub approvals list
-tangle hub approvals approve <approval-id>
-tangle hub approvals deny <approval-id>
+tangle secret create DATABASE_URL "postgres://..."
+tangle secret create API_KEY    # prompts interactively
+tangle secret list
+tangle secret show DATABASE_URL --reveal
+tangle secret update DATABASE_URL "new-value"
+tangle secret delete DATABASE_URL
+```
+
+## Snapshots & Checkpoints
+
+```bash
+# Snapshots (point-in-time for cloning/restoring)
+tangle snapshot create <sandbox-id>
+tangle snapshot list <sandbox-id>
+tangle snapshot restore <sandbox-id> <snapshot-id>   # creates new sandbox
+tangle snapshot revert <sandbox-id> <snapshot-id>    # reverts in-place
+tangle snapshot delete <sandbox-id> <snapshot-id>
+
+# Checkpoints (lightweight, local)
+tangle checkpoint create <id>
+tangle checkpoint list|ls <id>
+tangle checkpoint delete|rm <id> <checkpoint-id>
 ```
 
-`tangle hub resume <approval-id> --accept` is the approval-backed resume path for paused Hub executions. It resolves the approval and mints a short-lived capability token. It does not replay unknown input by itself; rerun the original `hub exec` with `--approve` for approve-and-retry automation.
+## Templates
+
+```bash
+tangle template list
+tangle template get <id-or-slug>
+tangle template versions <id-or-slug>
+tangle template publish <name> <snapshot-id> <sandbox-id>
+tangle template publish-version <id-or-slug> <snapshot-id> <sandbox-id>
+```
+
+## Teams
+
+```bash
+tangle team list
+tangle team create my-team
+tangle team switch my-team
+tangle team current
+tangle team clear
+tangle team members
+tangle team update-member <member-id>
+tangle team invite user@example.com
+tangle team leave [team]
+tangle team transfer <new-owner-customer-id> [team]
+tangle team accept <invitation-token>
+tangle team revoke-invitation <invitation-id>
+tangle team remove-member <member-id>
+tangle team secret              # Manage team secrets
+tangle team templates           # Manage team templates
+tangle team invitations [team]  # List pending/historical invitations
+```
+
+## Workflows
+
+```bash
+tangle workflows validate workflow.yml
+tangle workflows schema              # print JSON Schema
+tangle workflows create workflow.yml
+tangle workflows list
+tangle workflows get <id>
+tangle workflows update <id> workflow.yml
+tangle workflows delete <id>
+```
+
+## Other Commands
+
+```bash
+# Usage & billing
+tangle usage --json
+
+# API key management (id.tangle.tools)
+tangle keys list
+tangle keys create "my-key"
+tangle keys revoke <keyId>
+
+# Backend agent management
+tangle backend status <sandboxId>
+tangle backend configure <sandboxId>
+tangle backend restart <sandboxId>
+
+# Environments
+tangle env ls
+tangle env get <id>
+
+# Tools (mise)
+tangle tools ls <id>
+tangle tools install <id> python 3.12
+
+# Batch tasks across sandboxes
+tangle batch run --tasks tasks.json
+
+# Intelligence reports
+tangle intelligence sandbox <id>
+tangle intelligence fleet <id>
+tangle intelligence list
+tangle intelligence get <job-id>
+
+# Traces
+tangle traces list
+tangle traces get <traceId> --ndjson
+tangle traces runs
+
+# MCP bridge
+tangle mcp serve <id>
+
+# Preview links
+tangle preview ls <id>
+tangle preview create <id> 3000
+tangle preview rm <id> <preview-id>
+
+# Sandbox user permissions
+tangle permissions list <sandboxId>
+tangle permissions add <sandboxId> --userId <userId> --role editor
+```
+
+## Common Workflows
+
+| Goal | Commands |
+|------|----------|
+| Spin up sandbox, run agent | `tangle sandbox create --name X` → `tangle agent task <id> "..."` |
+| Connect GitHub, read issues | `tangle hub connect github` → `tangle hub tools search "issues" --provider github` → `tangle hub call github issues listIssues '{"owner":"X","repo":"Y"}'` |
+| Push code from sandbox to GitHub | `tangle hub connect github` → `tangle git add <id> files` → `tangle git commit <id> -m "msg"` → `tangle git push <id>` |
+| Save and restore state | `tangle snapshot create <id>` → ...work... → `tangle snapshot revert <id> <snap-id>` |
+| Set secret for agent use | `tangle secret create GITHUB_TOKEN "..."` → agent reads via `process.env.GITHUB_TOKEN` |
+| Set hub permissions | `tangle hub permissions set --connection conn_xxx --action github.issues.createIssue --decision allow` |
+| Batch parallel agent tasks | `tangle batch run --tasks tasks.json` (array of `{sandboxId, message}`) |
+
+## Common Mistakes
+
+- **Forgetting `--reveal` on `secret show`** — values are hidden by default for safety.
+- **Using API-key env and `TANGLE_HUB_CAPABILITY_TOKEN` together for hub** — set exactly one env auth source, or use `--api-key` to override both.
+- **Calling hub tools without `--approve` on first use** — use `--approve` or set policy to `allow` first.
+- **Missing `--json` flag when piping output** — many commands need explicit `--json` for machine-readable output.
+- **`tangle hub exec` vs `tangle exec`** — `hub exec` runs hub tools; `exec` runs shell commands in a sandbox.
+- **`hub resume` doesn't replay** — after `hub resume --accept`, rerun original `hub exec` with `--approve`.
 
-## Safety
+## Token Safety
 
-- Use `tools search`, then `tools describe`, then `call`.
-- Do not call unknown tools without inspecting schema.
-- Do not pass raw provider tokens to commands or env.
-- Treat `HUB_APPROVAL_REQUIRED` as approval-backed resume. Use `--approve` or `hub resume <approval-id> --accept`.
-- On `HUB_CONNECTION_MISSING`, run `tangle hub connect github`.
+Never print or log these in output: provider tokens, API keys, OAuth codes, refresh tokens, client secrets, capability tokens. Use `--json` for redacted machine output where supported.