> ## Documentation Index > Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt > Use this file to discover all available pages before exploring further. # lua browser > Read a page or run a browser task with the agent's browser from the terminal, and list or delete named browsers `lua browser` tries the agent's [browser](/reference/sdk/browser) from your terminal. `lua browser read` opens one page and prints it, like `Browser.read`. `lua browser run` gives the browser a task and prints each step as it happens, like `Browser.execute`. Both run on the platform with the agent you pushed, so you can check a page or a task before you write code for it. `lua browsers`, plural, is a different command: it lists and deletes the agent's [named browsers](/reference/sdk/browser#named-browsers). See [`lua browsers`](#lua-browsers) below. ## Synopsis ```bash theme={null} lua browser read [--selector ] [--format text|html] [--wait-for ] [-e ] [--agent-id ] [--json] lua browser run "" [--start-url ] [--schema ] [--max-steps ] [--max-cost ] [-e ] [--agent-id ] [--json] lua browsers [list|delete] [] [--browser-name ] ``` ## Description Both commands run against the agent in `lua.skill.yaml`, or the one named with `--agent-id`. They use that agent's browser settings as pushed: `engine`, `fallback`, `allowedDomains`, `confirmActions`, and `logContent`. Changes in your local code apply only after `lua push agent`. The agent needs `browser: true`, or the command fails with `BROWSER_DISABLED`. Your API key needs write access to the agent. With `--agent-id` the command does not need a project directory. Every read and run writes rows to the agent's logs on the `dev` channel, tagged with the environment from `-e`. Each command ends with a hint to read them: ```bash theme={null} lua logs --type browser ``` ### lua browser read Opens the URL in a new session, waits for `--wait-for` if given, prints the title, the final URL, the browser it ran on, and the content, then closes the session. When the page is a sign-in wall, it also prints `Blocked: yes` and what to do about it. The read has 60 seconds. ### lua browser run Starts the task and prints a line for each step as it arrives (`step 3: click on https://heylua.ai/pricing`), then the status, the number of steps, the cost, the browser it ran on, the final URL, and the output. A run that stops for an action in `confirmActions` prints `Waiting for confirmation:` and the action. * A run has 5 minutes. The CLI stops waiting after 6 minutes and exits `1`; read `lua logs --type browser` to see how far it got. * `Ctrl-C` cancels the run on the server, prints whether the server confirmed it, and exits `130`. * The command exits `1` when the run did not complete, for example when it hit `--max-steps` or `--max-cost`. ### Limits An agent runs at most 2 reads and runs from the CLI at a time. A third fails with `429` and `BROWSER_CLI_CONCURRENCY`; wait for one to finish, or press `Ctrl-C` on it. A slot also frees itself within 6 minutes, so a closed terminal never holds one for long. A `503` with `BROWSER_CLI_LIMITER_UNAVAILABLE` means CLI runs are paused for a moment; try again shortly. ## Arguments | Argument | Description | | - | - | | `url` | `read` only. An absolute `http://` or `https://` URL. | | `task` | `run` only. What the browser should do, in plain words. Quote it. | ## Options | Option | Description | Default | | - | - | - | | `--selector ` | `read` only. Print only the content of this CSS selector. | `body` | | `--format ` | `read` only. `text` or `html`. | `text` | | `--wait-for ` | `read` only. Wait for `load`, `networkidle`, or a CSS selector before reading. | none | | `--start-url ` | `run` only. The page the run starts on. | none | | `--schema ` | `run` only. A JSON Schema file the output must match. | none | | `--max-steps ` | `run` only. The most steps the run may take, from 1 to 60. | `25` | | `--max-cost ` | `run` only. The most the run may spend, in US dollars, as a plain decimal such as `0.50`. Above 0 and at most 10. | `1` | | `-e, --env ` | `sandbox`, `staging`, or `production`. `staging` is the same as `sandbox`. It only tags the log rows; the browser and its settings are the same. | `sandbox` | | `--agent-id ` | Run against this agent instead of the one in `lua.skill.yaml`. | `lua.skill.yaml` | | `--json` | Print the raw result as JSON. | off | ## Output `lua browser read --json` prints `{ engine, data, error?, code? }`. `data` has the fields of a [`Browser.read` result](/reference/sdk/browser#methods). A read the browser could not finish still exits `0` with `--json`; check `error` and `code`. `lua browser run --json` prints `{ id, status, result }` when the run ends, where `result` has the fields of a [`Browser.execute` result](/reference/sdk/browser#execute-result). After `Ctrl-C` it prints `{ id, status: "cancelled", cancelled }`. ## Examples Read a pricing page once it has finished loading: ```bash theme={null} lua browser read https://heylua.ai/pricing --wait-for networkidle ``` Read one element as HTML: ```bash theme={null} lua browser read https://heylua.ai/pricing --selector main --format html ``` Read a page with another agent, tagging the log rows as production, and pick out the title: ```bash theme={null} lua browser read https://heylua.ai/pricing --agent-id -e production --json | jq .data.title ``` Run a task from a start page: ```bash theme={null} lua browser run "Find the monthly price of the Pro plan" --start-url https://heylua.ai/pricing ``` Run a task with a schema and a spending cap: ```bash theme={null} lua browser run "Read the price and stock status" \ --start-url https://www.ikea.com/gb/en/p/billy-bookcase-white-00263850/ \ --schema product.schema.json --max-steps 10 --max-cost 0.25 ``` ## Exit codes | Code | Meaning | When | | - | - | - | | `0` | OK | The page was printed, or the run completed. | | `1` | Error | The browser could not read the page, the run did not complete, or the CLI stopped waiting after 6 minutes. | | `2` | Usage | A bad `-e`, `--format`, `--max-steps`, or `--max-cost`, an empty task, or a `--schema` file that can't be read or isn't a JSON object. | | `9` | Auth | No valid credential. | | `10` | Refused | The key can't run the browser for this agent (`403`), the agent has no browser (`409`, `BROWSER_DISABLED`), too many CLI runs (`429`, `BROWSER_CLI_CONCURRENCY`), or the server rejected an option, such as `--max-steps` over 60. | | `11` | Unavailable | CLI runs are paused (`503`, `BROWSER_CLI_LIMITER_UNAVAILABLE`), the cloud browser is not available in this environment (`503`, `BROWSER_WORKER_NOT_CONFIGURED`), or a network error. | | `130` | Cancelled | You pressed `Ctrl-C` during `run`. | The full table is in [Errors and exit codes](/reference/cli/errors-and-exit-codes). ## lua browsers `lua browsers` lists the named browsers pushed to the agent, one per line with its engine and allowed domains. `lua browsers delete` deletes one from the agent and removes it from `lua.skill.yaml`; remove it from the agent's `browsers` list too, then push again. Named browsers are pushed with `lua push browser --name ` or `lua push all`. | Argument or option | Description | Default | | - | - | - | | `action` | `list` or `delete`. Aliases: `ls`, `l` for `list`; `rm`, `remove`, `del` for `delete`. | `list` | | `name` | The browser to delete. Same as `--browser-name`. | — | | `--browser-name ` | The browser to delete. | — | ```bash theme={null} lua browsers lua browsers delete --browser-name supplier-portal ``` `delete` without a name exits `2` and lists the agent's browsers; an unknown name exits `3`. ## See also * [`Browser`](/reference/sdk/browser) — `Browser.read`, `Browser.execute`, named browsers, limits, and error codes * [`LuaAgent`](/reference/sdk/luaagent) — the `browser` and `browsers` options * [`lua logs`](/reference/cli/logs) — `--type browser` shows the rows each read and run wrote * [`lua push`](/reference/cli/push) — push the agent and its named browsers This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.