https://docs.notte.cc/llms.txt

undefined

undefined

notte auth login

notte auth status

undefined

undefined

undefined

> **Sessions expire sooner than you might expect.** A session closes after
> **3 minutes idle** or **15 minutes total**, whichever comes first. Long
> exploration, a slow login, or a pause for user confirmation can all outlast
> that, and the next command then fails with `Session closed` rather than
> anything descriptive. Raise both when the task will not finish quickly:
>
> ```bash
> notte sessions start --idle-timeout-minutes 15 --max-duration-minutes 60
> ```

**Skill rule:** Always save the `session_id` returned by `sessions start` and
pass it as `--session-id` to every `page`, targeted `sessions`, and session-file
command. Do not rely on the CLI's current-session or environment-variable
fallback behavior.

**Browser profiles:** Profiles store browser state such as cookies, `localStorage`, and `sessionStorage`. Start a session with `--profile-id <profile-id>` to load that saved state; add `--profile-persist` when starting the session if changes should be saved back to the profile when the session closes.

Session debugging:

```bash

Session export:

```bash

    # directly parses the output using response_format and returns the Model
    return session.scrape(instructions='Extract the top 10 stories from Hacker News. For each story return: rank, title, URL, points, author, number of comments', only_main_content=False, only_images=False, scrape_links=True, scrape_images=False, response_format=Model)

Cookie management:

```bash

undefined

undefined

**Run JavaScript in the page:**

- Escape single quotes if needed.
- `console.log` output is discarded - only the returned value comes back.
- Use a single expression, or a function that returns a value.
- **The returned value is printed alone on stdout** (objects and arrays as JSON,
  a JS `null` as `null`), with the status line on stderr - so it captures into a
  shell variable and pipes without post-processing. Use `-o json` when you want
  the whole execution result instead.
- A failing script exits non-zero and reports the actual JavaScript error, so
  `set -e` and `||` fallbacks behave.

```bash

Return `JSON.stringify(...)` whenever the answer is structured: it arrives as a
JSON document, so `jq` does the filtering instead of another round trip through
the page.

**Navigation:**
```bash
notte page goto --session-id <session-id> "https://example.com"
notte page new-tab --session-id <session-id> "https://example.com"
notte page back --session-id <session-id>
notte page forward --session-id <session-id>
notte page reload --session-id <session-id>

notte page scroll-down --session-id <session-id> [amount]
notte page scroll-up --session-id <session-id> [amount]

notte page press --session-id <session-id> "Enter"
notte page press --session-id <session-id> "Escape"
notte page press --session-id <session-id> "Tab"

notte page switch-tab --session-id <session-id> 1
notte page close-tab --session-id <session-id>

undefined

`--only-main-content` can reduce output size and token cost by filtering out
navigation, sidebars, footers, and other page chrome. It can also reduce recall,
especially on dynamic pages or layouts where important content is not classified
as main content. When completeness matters, try scraping without
`--only-main-content` first, then add it only if the full-page output is too
noisy or expensive.

**Utilities:**
```bash

CAPTCHA solving is enabled automatically for a session unless it was started
with `--no-solve-captchas`. If a Cloudflare WAF interstitial or Turnstile
challenge is still visible, explicitly run `captcha-solve` with the
`cloudflare` type before continuing with page actions.

undefined

**Skill rule:** Always save the `function_id` returned by `functions create` (or
obtain it from `functions list`) and pass it as `--function-id` to every command
that targets a Function. Do not rely on the CLI's current-Function fallback.

**Reading a run result.** `notte functions run --function-id <function-id>` blocks server-side and returns `status` and `result` together. Judge the run on **`result`**, not `status` alone - a successful run reports `status: "closed"`, and so does a run that raised inside `run()`, with the error text in `result`. `result` is the return value of `run()` serialized to JSON: a `dict` comes back as a real nested object, a `str` as a JSON string. A string containing `Script execution failed` or a `Traceback` is a failure.

The response also carries `function_run_id`, `session_id`, and `workflow_run_id`:

```json
{"function_id": "...", "function_run_id": "...", "result": {"count": 1},
 "session_id": null, "status": "closed", "workflow_id": "...", "workflow_run_id": "..."}

RID=$(notte functions run --function-id "$FUNCTION_ID" -o json | jq -r '.function_run_id')
notte functions run-metadata --function-id "$FUNCTION_ID" --run-id "$RID" -o json | jq -r '.logs[]'

undefined

**Phone numbers are a gated feature.** `notte personas create --create-phone-number` will **fail** on a standard account - phone-number provisioning is unlocked per-account by the Notte team. Without it, the persona has an email inbox but no number, and `notte personas sms` has nothing to return.

Do not retry the command or work around it; it is an account entitlement, not a transient error. To request access, book a 15-minute call:

```text
https://cal.com/pintoa/15mins

undefined

undefined

notte files upload <local-path>                                      # local machine -> uploads store
notte files list --from uploads                                      # account uploads
notte files download <filename> --from uploads [--path <local-path>]
notte files list --from session --session-id <session-id>            # session downloads
notte files download <filename> --from session --session-id <session-id> [--path <local-path>]

notte files upload ./invoice.pdf                      # 1. into the uploads store
notte page upload --session-id <session-id> "#file-input" --file invoice.pdf    # 2. into the page
notte page click --session-id <session-id> "#submit"

notte page observe --session-id <session-id>                                    # required before using an element ID
notte page download --session-id <session-id> "L3"                              # -> the session store, still remote
notte files list --from session --session-id <session-id>                       # confirm it arrived
notte files download report.csv --from session --session-id <session-id> --path ./report.csv

undefined

Typical use - log in once, persist the state, then reuse it without logging in again:

```bash
PROFILE_ID=$(notte profiles create -o json | jq -r '.profile_id')

undefined

notte search "latest llm releases"
notte search "what is anthropic" --depth deep
notte search "what is anthropic" --output-type sourcedAnswer

  --depth         standard (default), fast, or deep
  --output-type   searchResults (default), sourcedAnswer, or structured

notte usage      # Show API usage statistics
notte health     # Check API health status
notte clear      # Clear legacy stored CLI resource pointers

--output, -o    Output format: text, json (default: text)
--timeout       API request timeout in seconds (default: 60)
--no-color      Disable color output
--verbose, -v   Verbose output
--yes, -y       Skip confirmation prompts

undefined

undefined

SESSION_ID=$(notte sessions start -o json | jq -r '.session_id')
notte page goto --session-id "$SESSION_ID" "https://example.com/signup"
notte page fill --session-id "$SESSION_ID" "#email-field" "user@example.com"
notte page fill --session-id "$SESSION_ID" "#password-field" "securepassword"
notte page click --session-id "$SESSION_ID" "#submit-button"
notte sessions stop --session-id "$SESSION_ID"

undefined

**Named vault fields.** Pass one of these names to `--vault-field`; the CLI maps
it to the placeholder that Notte replaces with the matching vault credential
before the keystrokes hit the page. Do not write sentinel strings directly.

| Credential | `--vault-field` value |
|------------|-----------------------|
| email      | `email`               |
| username   | `username`            |
| password   | `password`            |
| MFA code   | `mfa`                 |

undefined

undefined

undefined

**Handling multiple matches** - Use `>> nth=0` to select the first match:

```bash

undefined

undefined

undefined

undefined

undefined

notte sessions stop --session-id <session-id>
notte sessions start --proxy