lua browser

lua browser tries the agent’s 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. See lua browsers below.

Synopsis

lua browser read <url> [--selector <css>] [--format text|html] [--wait-for <what>]
                       [-e <environment>] [--agent-id <agentId>] [--json]
lua browser run "<task>" [--start-url <url>] [--schema <file.json>] [--max-steps <n>] [--max-cost <usd>]
                         [-e <environment>] [--agent-id <agentId>] [--json]

lua browsers [list|delete] [<name>] [--browser-name <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:

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 <css>`	`read` only. Print only the content of this CSS selector.	`body`
`--format <format>`	`read` only. `text` or `html`.	`text`
`--wait-for <what>`	`read` only. Wait for `load`, `networkidle`, or a CSS selector before reading.	none
`--start-url <url>`	`run` only. The page the run starts on.	none
`--schema <file.json>`	`run` only. A JSON Schema file the output must match.	none
`--max-steps <n>`	`run` only. The most steps the run may take, from 1 to 60.	`25`
`--max-cost <usd>`	`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 <environment>`	`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 <agentId>`	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. 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. After Ctrl-C it prints { id, status: "cancelled", cancelled }.

Examples

Read a pricing page once it has finished loading:

lua browser read https://heylua.ai/pricing --wait-for networkidle

Read one element as HTML:

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:

lua browser read https://heylua.ai/pricing --agent-id <agentId> -e production --json | jq .data.title

Run a task from a start page:

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:

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.

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 <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 <name>`	The browser to delete.	—

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.

SDK

CLI

REST API

Synopsis

Description

lua browser read

lua browser run

Limits

Arguments

Options

Output

Examples

Exit codes

lua browsers

See also

​Synopsis

​Description

​lua browser read

​lua browser run

​Limits

​Arguments

​Options

​Output

​Examples

​Exit codes

​lua browsers

​See also

Synopsis

Description

lua browser read

lua browser run

Limits

Arguments

Options

Output

Examples

Exit codes

lua browsers

See also