# rexa web

> Drive a Rexa browser tab from the command line.

`rexa web` controls a browser tab in the running Rexa app. Agents use it to open pages, read them and act on them; you can run it from any terminal too.

```bash [Terminal]
rexa web open http://localhost:3000   # open a page
rexa web snapshot                     # list elements with @e refs
rexa web click @e4                    # click one
rexa web console                      # read console output
rexa web screenshot -o page.png       # save a screenshot
```

## Which browser a command acts on

Rexa picks the first that applies:

1. `--browser <id>`
2. the `REXA_BROWSER` environment variable
3. the browser linked to the calling agent
4. for an agent, a new browser tab linked to it
5. from a plain shell, the active worktree's shown browser, or a new one

Browsers are numbered `b1`, `b2`, … and keep their ids across a relaunch. Driving an unlinked browser with `--browser` links it to the calling agent.

## Global flags

<FieldGroup>
  <Field name="--json">Print the app's raw reply.</Field>
  <Field name="--browser" type="<id>">Act on one browser.</Field>
</FieldGroup>

A command fails with exit status 1 on error, and when no Rexa app is running. The app answers within 30 seconds.

## Targets

Commands that act on an element take a target:

| Form             | Example                  | Lifetime                                    |
| ---------------- | ------------------------ | ------------------------------------------- |
| `@eN`            | `@e12`                   | From `snapshot`; valid until the page changes. |
| `role:<role> "<name>"` | `role:button "Save"` | Survives re-renders.                        |
| `css:<selector>` | `css:#email`             | Add `>>>` to reach into a same-origin iframe. |

## Navigation

| Command                 | Flags                                  | Does                                        |
| ----------------------- | -------------------------------------- | ------------------------------------------- |
| `status`                |                                        | URL, loading state, history, page N of M.   |
| `open <url>`            | `--show`, `--new-tab`, `--browser-tab` | Navigate. `--new-tab` opens a new page; `--browser-tab` opens a new linked browser tab. |
| `back`, `forward`, `reload` |                                    | History.                                    |
| `url`                   |                                        | Print the URL only.                         |
| `pages`                 |                                        | List pages in this browser.                 |
| `new-page [url]`        |                                        | Open a page.                                |
| `select-page <N>`       |                                        | Show page N.                                |
| `close-page [N]`        |                                        | Close a page.                               |
| `browsers`              |                                        | Every browser with id, place, URL and agent. `*` marks yours. |
| `link`                  | `--unlink`                             | Link or unlink this browser to the calling agent. |
| `devtools`              |                                        | Open the Web Inspector.                     |

## Reading the page

| Command               | Flags                                           | Does                                        |
| --------------------- | ----------------------------------------------- | ------------------------------------------- |
| `snapshot`            |                                                 | Named and interactive elements with `@e` refs. |
| `text [target]`       |                                                 | Visible text, a field's value, or a checkbox state. |
| `screenshot [target]` | `-o, --output <path>`, `--full`, `--format png\|jpeg` | Save an image. `--full` captures the whole page. |
| `console`             | `--follow`, `--detail <seq>`                    | The last 500 console entries and errors.    |
| `requests`            | `--follow`, `--detail <seq>`                    | Fetch and XHR log. `--detail` shows headers and bodies up to 64 KB. |
| `vitals`              |                                                 | TTFB, FCP, LCP, CLS and INP where WebKit reports them. |
| `dialogs`             | `--follow`                                      | Dialog history and how each was answered.   |

## Acting on the page

| Command                       | Flags                         | Does                                        |
| ----------------------------- | ----------------------------- | ------------------------------------------- |
| `click <target>`              | `--right`, `--double`         | Click.                                      |
| `type <target> <text>`        | `--submit`                    | Replace a field's text; `--submit` presses Enter. |
| `fill <target> <value> …`     |                               | Fill several fields. A value can be `checked` or `unchecked`. |
| `press <key>`                 |                               | `Enter`, `Escape`, `Tab`, `shift+Tab`, `cmd+k`, … |
| `hover <target>`              |                               | Hover, including CSS `:hover`.              |
| `select <target> <option>`    |                               | Pick a `<select>` option by value or label. |
| `check <target>`, `uncheck <target>` |                        | Checkbox, switch or radio.                  |
| `drag <from> <to\|dx,dy>`     |                               | Drag onto an element or by an offset.       |
| `upload <target> <files…>`    |                               | Set a file input. 25 MB total.              |
| `scroll [target]`             | `--by <px>`                   | Scroll an element into view, or the page.   |
| `wait [target]`               | `--text`, `--url`, `--timeout <ms>` | Wait for an element, text or URL. Default 5000 ms, max 25000. |
| `dialog accept\|dismiss [text]` |                             | Answer the next page dialog.                |
| `eval <script>`               |                               | Run JavaScript. Off unless the app started with `REXA_WEB_ALLOW_EVAL` set. |

## Page settings

| Command                | Flags                                                     | Does                                  |
| ---------------------- | --------------------------------------------------------- | ------------------------------------- |
| `resize <WxH\|fit>`    |                                                           | Pin the page size, or fill the pane.  |
| `emulate`              | `--user-agent <ua>`, `--color-scheme light\|dark\|system`, `--reset` | Override the user agent or color scheme. |

## Cookies

| Command                       | Flags                                | Does                                        |
| ----------------------------- | ------------------------------------ | ------------------------------------------- |
| `cookie-sources`              |                                      | List local Firefox, Chrome, Chrome Beta, Edge and Brave profiles. Reads no cookies. |
| `import-cookie <url>`         | `--from firefox\|chrome`, `--profile <id>` | Import that site's cookies.           |

- **Always pass `--from`.** Without it, Rexa picks the first browser it finds.
- **Firefox** needs `--profile` when there are several profiles, and asks for confirmation in the app.
- **Chrome** asks `[y/N]` in the terminal, so it needs an interactive shell. macOS may ask for Keychain access.
- **Edge, Brave and Chrome Beta** are listed but cannot be imported. Safari is not supported.