> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> Use the Runtools command-line interface

`runtools` is the command line to the whole platform — auth, projects, sandboxes, agents, tools, secrets, SSH keys, threads, devices, and usage. Anything you can do in the dashboard, you can script.

```bash theme={null}
npm install -g @runtools-ai/cli
```

## Quick Start

```bash theme={null}
runtools login
runtools sandbox create --name my-env --template base-ubuntu
runtools sandbox create --name agent-env --template base-ubuntu --mount 9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e:/workspace
runtools sandbox exec my-env "echo hello"
runtools agent run code-assistant "Create a REST API"
runtools deploy --dry-run
```

Use `--mount <workspaceId[:path]>` when a sandbox-backed agent needs durable storage. The path defaults to `/workspace`.

## Command Groups

| Group              | Commands                                                                         |
| ------------------ | -------------------------------------------------------------------------------- |
| Auth               | `login`, `logout`, `auth whoami`, `auth status`, `auth set-key`, `auth keys ...` |
| OAuth              | `oauth connect`, `oauth status`, `oauth disconnect`, `oauth set-default`         |
| Project            | `init`, `deploy`                                                                 |
| Sandboxes          | `sandbox create/list/get/exec/ssh/url/logs/watch/pause/resume/destroy`           |
| SSH keys           | `ssh-key list/add/remove/set-default/set-always-include`                         |
| Agents             | `agent list/get/run/delete/publish/install/sandbox/threads`                      |
| Tools              | `tool search/list/install/uninstall/exec/credentials/publish/delete`             |
| Secrets            | `secret set/list/get/rotate/delete`                                              |
| Threads            | `threads list/get/events/rollouts/compact/archive/stream`                        |
| Devices            | `devices list/rename/revoke/audit/register`                                      |
| Installable agents | `installable-agent list/installs/install`                                        |
| Usage              | `usage`                                                                          |

## Global Patterns

Many list and mutation commands support `--json` for scripts:

```bash theme={null}
runtools sandbox list --json
runtools agent run code-assistant "Summarize this repo" --json
```

Admin-only broader org views use `--all-org` where supported.

## Environment Variables

| Variable             | Purpose                          |
| -------------------- | -------------------------------- |
| `RUNTOOLS_API_KEY`   | API key for non-interactive auth |
| `RUNTOOLS_API_URL`   | Orchestrator API override        |
| `RUNTOOLS_AUTH_URL`  | Auth service override            |
| `RUNTOOLS_TOOLS_URL` | Tools service override           |

## Config Files

The CLI stores local credentials and settings in `~/.runtools/`.

Use API keys for CI:

```bash theme={null}
runtools auth set-key "$RUNTOOLS_API_KEY"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/cli/installation">
    Install from npm and verify your setup.
  </Card>

  <Card title="Authentication" icon="key" href="/cli/authentication">
    Sign in, create keys, and use CI auth.
  </Card>

  <Card title="Commands Reference" icon="book" href="/cli/commands">
    See implemented commands and flags.
  </Card>
</CardGroup>