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

# CLI

> Control Rusty Browser from the terminal with rusty-cli

## Overview

`rusty-cli` is a thin command-line interface for the `rusty-server` HTTP API. It wraps every API endpoint as a typed command and tracks the last active browser so you can omit the ID on repeated calls.

## Installation

```bash theme={null}
# Install from the repo
cargo install --path rusty-cli

# Or build manually
cd rusty-cli
cargo build --release
# binary: target/release/rusty-cli
```

## Configuration

The CLI reads config from three sources, in order of precedence:

1. **Command-line flags**: `--url`, `--api-key`
2. **Environment variables**: `RUSTY_URL`, `RUSTY_API_KEY`
3. **Stored config**: `~/.rusty-cli.json` (Windows: `%USERPROFILE%\.rusty-cli.json`)

Save the local server URL so you don't have to pass it every time:

```bash theme={null}
rusty-cli env set url http://127.0.0.1:8080
rusty-cli env show
```

Set `api-key` only if your `rusty-server` config enforces `X-API-Key`:

```bash theme={null}
rusty-cli env set api-key your-local-key
```

## Quickstart

```bash theme={null}
# First-time setup: provisions certs and registers the agent function
rusty-cli init

# Spawn a browser (execution_id is stored automatically as "last browser")
rusty-cli browser spawn

# Drive it
rusty-cli browser navigate https://example.com
rusty-cli browser screenshot > shot.json
rusty-cli browser instruct "find the login link and click it"
rusty-cli browser logs

# Clean up
rusty-cli browser close-all
rusty-cli teardown
```

## Commands

### Top-level

| Command                 | Description                                                          |
| ----------------------- | -------------------------------------------------------------------- |
| `init`                  | `POST /initialize/`: provision certs and register the agent function |
| `teardown`              | `DELETE /teardown/`: close all browsers and terminate all nodes      |
| `env set <key> <value>` | Persist a config value (`url` or `api-key`)                          |
| `env show`              | Print current config and file location                               |

### Browser Lifecycle

| Command                                   | Description                                                           |
| ----------------------------------------- | --------------------------------------------------------------------- |
| `browser spawn [--identity <json>]`       | Spawn a browser. Stores the returned `execution_id` as "last browser" |
| `browser list`                            | List all active browsers                                              |
| `browser get [id]`                        | Get details for one browser                                           |
| `browser close [id]`                      | Close and deregister one browser                                      |
| `browser close-all`                       | Close every active browser                                            |
| `browser create-context [id]`             | Open a new isolated tab (context)                                     |
| `browser close-context [id] <context_id>` | Close a specific tab                                                  |

### Navigation & Interaction

| Command                                    | Notes                                            |
| ------------------------------------------ | ------------------------------------------------ |
| `browser navigate [id] <url>`              | Load a URL and wait for page load                |
| `browser click [id] <x> <y>`               | Click at pixel coordinates                       |
| `browser node-click [id] <node_id>`        | Click a node by ID (get one from `find-node`)    |
| `browser type [id] <text> [--node-id <n>]` | Type into the focused element or a specific node |
| `browser scroll-by [id] <y>`               | Scroll by Y pixels (positive = down)             |
| `browser scroll-to [id] <node_id>`         | Scroll a node into view                          |
| `browser send-keys [id] <keys>`            | e.g. `"Backspace, Backspace"` comma-separated    |
| `browser hold-key [id] <key>`              | e.g. `"Backspace3000"` = hold for 3000 ms        |

### DOM Queries

Use `find-node` for a specific selector, or `ui-map` when you need to inspect the full accessibility tree before choosing a node ID.

| Command                                                        | Notes                                             |
| -------------------------------------------------------------- | ------------------------------------------------- |
| `browser find-node [id] <css-selector>`                        | Returns a `node_id` for use in click/type/fetch   |
| `browser wait-for-node [id] <css-selector> [--timeout-ms <n>]` | Default timeout: 5000 ms                          |
| `browser fetch-html [id] [--node-id <n>]`                      | Inner HTML of a node, or full document if omitted |
| `browser fetch-text [id] <node_id>`                            | Inner text of a node                              |
| `browser ui-map [id]`                                          | Dump the full accessibility tree                  |
| `browser ui-map-diff [id]`                                     | Diff against the last `ui-map` call               |
| `browser eval [id] <script>`                                   | Evaluate JavaScript and print the result          |

### AI & Logs

| Command                               | Notes                                                                             |
| ------------------------------------- | --------------------------------------------------------------------------------- |
| `browser instruct [id] <instruction>` | Run a natural language instruction. Returns 202 immediately; use `logs` to follow |
| `browser logs [id]`                   | Fetch execution logs                                                              |

## ID Resolution

Almost every `browser` subcommand takes an optional `[id]` positional. When omitted, the CLI uses the last `execution_id` returned from `spawn`, stored in `~/.rusty-cli.json`.

To target a specific browser without changing the stored default, pass the ID explicitly:

```bash theme={null}
rusty-cli browser navigate exc-abc123 https://example.com
```

## Notes

* The CLI sends `X-API-Key` only when an API key is configured.
* `instruct` is fire-and-forget: the server runs the AI loop in the background. Poll `logs` to follow progress.