Overview
| Command | Description | Cost |
|---|
naive browser session create | Open a live browser session | 0 credits |
naive browser session status <id> | Check a session’s status | — |
naive browser session close <id> | Close a session | time floor (1–3) |
naive browser navigate <id> <url> | Navigate to a URL | 1 credit |
naive browser act <id> <instruction> | Natural-language action | 1 credit |
naive browser extract <id> <instruction> | Extract structured data | 1 credit |
naive browser observe <id> <instruction> | List candidate elements | 1 credit |
naive browser screenshot <id> | Capture the page (signed URL) | 1 credit |
naive browser signup <service> <url> | Autonomous account creation | 4 credits |
naive browser login <service> <url> | Autonomous re-login from the vault | 3 credits |
naive browser context save <id> | Persist a human login as a saved context | — |
naive browser context grant <name> | Grant an agent/role access to a saved login (human-only) | — |
naive use <id> / --user) or the workspace default.
Sessions
naive browser session create --allowed-domains example.com,docs.example.com --timeout 15
naive browser session create --allowed-domains '*' --allow-writes
naive browser session status <session_id>
naive browser session close <session_id>
session create options
| Flag | Description |
|---|
--allowed-domains <list> | Required. Comma-separated allowlist (default-deny). Use '*' to browse unrestricted (not recommended). |
--allow-writes | Permit write/destructive act() instructions (default off). |
--timeout <minutes> | Hard session TTL (default 15, max 30). |
--context-name <name> | Reopen a saved login by name (requires a grant). |
--human-login | Open a human first-login session (agents locked out until context save). |
--allow-extract | On a saved-login session, permit extract/observe/screenshot. |
--proxy | Route egress through a residential proxy (requires --allowed-domains). |
Drive a session
naive browser navigate <session_id> https://example.com
naive browser act <session_id> "click the login button"
naive browser extract <session_id> "the list of product names and prices"
naive browser observe <session_id> "the buttons that add an item to the cart"
naive browser screenshot <session_id>
act and navigate send a stable Idempotency-Key automatically so a retried logical step never double-submits. Never put passwords or secrets in an instruction.
Autonomous signup & login
# Create an account: generates a strong password, fills the form, vaults the credential
naive browser signup figma.com https://www.figma.com/signup
# Re-authenticate later using the vaulted credential
naive browser login figma.com https://www.figma.com/login
Options (both)
| Flag | Description |
|---|
--allowed-domains <list> | Override the session allowlist (defaults to the URL’s host). |
--timeout <minutes> | Hard session TTL (default 15, max 30). |
signup may require human approval depending on the user’s Account Kit. When gated it returns status: "pending_approval" and runs only after naive approvals approve <id>. The generated password is stored in the user’s vault under login:<service> and never printed.
Output
{
"success": true,
"action": "browser.signup",
"result": {
"success": true,
"service": "figma.com",
"credential_saved": true,
"credits_used": 4,
"credits_remaining": 96
},
"next_steps": [
{ "command": "naive browser login figma.com https://www.figma.com/login", "description": "Log back in later using the saved credential" }
]
}
Saved logins
# After a human completes a login in a --human-login session's live view:
naive browser context save <session_id>
# Grant an agent or role access to a saved login (human session only):
naive browser context grant figma --type role --id ops
context grant and revoke are human-only (use ≠ destroy). The CLI authenticates with an agent key, so grants are normally created from the dashboard. An agent can use a granted saved login but can never create the grant or revoke a shared login.
