---
name: tangle-cli
description: Use Tangle Sandbox CLI for lifecycle, prompts, files, fleets, Hub tools, and integrations.
---

# Tangle CLI

## Overview

`tangle` is the CLI for Tangle Sandbox operations: create sandboxes, run agents, execute hub tools, and manage files, secrets, snapshots, and git.
All commands support `--help` for inline reference.

## Auth

Generic command auth modes, resolved in order:

| Priority | Source | Set via |
|----------|--------|--------|
| 1 | CLI flag | `--api-key <key>` |
| 2 | Env var | `TANGLE_API_KEY` |
| 3 | Profile store | `tangle auth login` (keychain or file) |

Hub commands resolve auth in this order:

| Priority | Source | Set via |
|----------|--------|--------|
| 1 | CLI flag | `--api-key <key>` |
| 2 | Hub capability | `TANGLE_HUB_CAPABILITY_TOKEN` |
| 3 | Env var | `TANGLE_API_KEY` |
| 4 | Profile store | `tangle auth login` (keychain or file) |

**Inside a sandbox:** `tangle` is automatically authenticated.
No extra authentication is needed.

```bash
# 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
```

For hub env auth, set **exactly one** of `TANGLE_API_KEY` or `TANGLE_HUB_CAPABILITY_TOKEN`.

## Sandbox Lifecycle

```bash
# 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>
```

## Temporary GPUs

Use a normal sandbox first, then attach a GPU only for the work that needs it.
Omit `--provider` to use the cheapest configured GPU cloud.
Always set a spend cap and lifetime.

```bash
# One-shot eval: attach GPU, run command, always destroy the lease.
tangle sandbox gpu run <sandbox-id> \
  --accelerator-kind nvidia-3090 \
  --accelerator-memory 24000 \
  --max-spend-usd 1 \
  --max-lifetime 900 \
  --idle-timeout 120 \
  -- python eval.py

# Manual lifecycle when the agent needs multiple GPU commands.
tangle sandbox gpu attach <sandbox-id> \
  --accelerator-kind nvidia-3090 \
  --accelerator-memory 24000 \
  --max-spend-usd 1 \
  --max-lifetime 900 \
  --idle-timeout 120
tangle sandbox gpu exec <sandbox-id> <gpu-lease-id> -- python eval.py
tangle sandbox gpu detach <sandbox-id> <gpu-lease-id>
```

For fleets, put the same GPU lease cap on every worker:

```bash
tangle fleet create --count 4 \
  --accelerator-kind nvidia-3090 \
  --accelerator-memory 24000 \
  --gpu-max-spend-usd 1 \
  --gpu-max-lifetime 900 \
  --gpu-idle-timeout 120
```

## Full Hub Workflow

Hub lets agents use connected provider tools (GitHub, etc.) through Tangle without seeing provider OAuth tokens.

### Auth Check & Connection

```bash
# 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
```

### 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.search --json
```

### Tool Execution

Two equivalent commands are available: `call` and `exec`.

```bash
# Basic call: <path tokens...> <json-input>
tangle hub call github issues search '{"q":"repo:tangle-network/agent-dev-container is:issue"}'
tangle hub exec github.issues.search '{"q":"repo:tangle-network/agent-dev-container is:issue"}'

# With explicit connection
tangle hub call github issues createIssue '{"owner":"foo","repo":"bar","title":"Fix bug"}' --connection conn_xxx
```

### Policy & Approvals

Tools default to the `ask` policy.
They pause and require approval on first use.

```bash
# 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.search --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
```

### Auto-Approve Execution

When you expect `HUB_APPROVAL_REQUIRED`, approve and retry in one command:

```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 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
```

## Secrets

Secrets are scoped to your account (or team). Use `--reveal` to see values.

```bash
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

```bash
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>
```

## 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

Authenticate with the `sk-tan-*` API key (`TANGLE_API_KEY`), same as the other
platform commands, not a hub capability token.

```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 enable <id>
tangle workflows disable <id>
tangle workflows delete <id>

# Runs
tangle workflows run <id>                                   # trigger a run
tangle workflows run <id> --input pull_request.number=123   # with trigger inputs
tangle workflows run <id> --wait                            # wait + print result
tangle workflows runs <id>                                  # run history
tangle workflows run-detail <id> <runId>                    # single-run detail
tangle workflows events <id> <runId>                        # tail live progress
```

## 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
tangle batch run --tasks tasks.json --backend writer=opencode --backend reviewer=claude-code --stream

# 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 prompt <id> "..."` |
| Connect GitHub, read issues | `tangle hub connect github` → `tangle hub tools search "issues" --provider github` → `tangle hub call github issues search '{"q":"repo:X/Y is:issue"}'` |
| 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 prompts | `tangle batch run --tasks tasks.json --backend primary=opencode` (array of `{id, message}`) |
| Compare backends on the same tasks | `tangle batch run --tasks tasks.json --backend writer=opencode --backend reviewer=claude-code --stream` |

## 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` 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` does not replay:** after `hub resume --accept`, rerun the original `hub exec` with `--approve`.

## Token Safety

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.