CLI

The nodemantis command line is included in the node-mantis package on npm and PyPI. Use it to run browser goals, retrieve data, configure credentials, and check your installation. Both packages install the equivalent commands nodemantis and node-mantis.

This page documents the command-line surface: flags, output contracts, exit codes, and configuration. The flags mirror the SDK options — what they mean (effort levels, budgets, retrieval statuses and result fields) is defined once in the API reference.

Choose one installation method below. Each installs the CLI and its compiled runtime. Google Chrome must also be installed. If you have multiple installations, the first nodemantis on your PATH runs.

npm install -g node-mantis

# Run without a global installation
npx node-mantis doctor

python -m pip install --upgrade "node-mantis"

# Or install the CLI in an isolated environment
pipx install "node-mantis"

# Run using a specific Python environment
python -m nodemantis doctor

brew install node-mantis/tap/nodemantis

Have Google Chrome installed, set a key, then run a goal. The key can also come from the environment instead of the config file.

export NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>"   # or persist it:
nodemantis configure --api-key "sk_live_<copy-from-dashboard>"
nodemantis doctor
nodemantis run \
  "Find the cheapest in-stock Travel & Adventure book. Report its title and price." \
  --url https://sandbox.nodemantis.com \
  --max-iterations 20

Flags are grouped by the command that accepts them.

Runs a multi-step browser goal, narrating each iteration on stderr while it works. Every run returns a summary. Pass --schema to request structured data as well.

nodemantis run \
  "Find the cheapest in-stock Travel & Adventure book. Report its title and price." \
  --url https://sandbox.nodemantis.com \
  --max-iterations 20

Opens a page and returns grounded data for a prompt. --url is required. Statuses and result fields follow the retrieve contract in the API reference.

nodemantis retrieve "Read this book's title and price in USD." \
  --url https://sandbox.nodemantis.com/books/journey-to-the-center-of-the-earth \
  --schema '{"type":"object","properties":{"title":{"type":"string"},"priceUsd":{"type":"number"}},"required":["title","priceUsd"],"additionalProperties":false}'

To use a schema saved in books.json and print JSON output:

nodemantis retrieve "Read the book titles and prices." -u https://sandbox.nodemantis.com -s books.json -j

Stores credentials in the user config file, created with 0600 permissions. On an interactive terminal it prompts for anything not passed as a flag. See Configuration file for the file locations.

Checks your configuration, runtime, and browser against a local test page, then verifies your API key with the hosted service and checks for updates. Reports problems with guidance for fixing them. It does not run an AI task. Use --offline to skip network checks.

During a run, progress messages describe the agent's next action. These messages are written to stderr:

[1/20] The homepage has a Travel & Adventure category link in the main navigation; open it to compare relevant books. — click("Travel & Adventure")
[2/20] The Travel & Adventure catalogue shows four books and an unchecked In stock only filter. Enable it before sorting by price. — click("on")
[3/20] In stock only is checked, while Sort by remains Our shelf order. Select ascending price to identify the cheapest available book. — select("featured")
[4/20] In stock only is checked and Price: low to high is selected; apply these filters to obtain the cheapest available book. — click("Apply filters")
[5/20] retrieve
[6/20] done
Browser session closed.

Final results are written to stdout. Progress stays on stderr so you can pipe results to another program while watching the run in your terminal. Use -q or --quiet to hide progress.

With --json, stdout carries exactly one JSON object: the result on success, or an {"error": {...}} envelope when the command fails. All human-readable output stays on stderr, so the command pipes cleanly:

nodemantis retrieve "Read this book's title and price in USD." \
  --url https://sandbox.nodemantis.com/books/journey-to-the-center-of-the-earth \
  --schema '{"type":"object","properties":{"title":{"type":"string"},"priceUsd":{"type":"number"}},"required":["title","priceUsd"],"additionalProperties":false}' --json | jq .status

• 0 — success: the task succeeded, the data was found, or every check passed.
• 1 — negative outcome: the task failed, the data was not found, a check failed, or an error occurred.
• 2 — usage or configuration error, such as an unknown flag or a missing required value.
• 130 — interrupted.

configure writes, and every command reads, a per-user JSON config file created with 0600 permissions:

• macOS: ~/Library/Application Support/nodemantis/config.json
• Linux: $XDG_CONFIG_HOME/nodemantis/config.json
• Windows: %APPDATA%\nodemantis\config.json

Set NODEMANTIS_CONFIG_FILE to override the location. The API key resolves in this order: --api-key, then NODEMANTIS_API_KEY, then NODEMANTIS_AUTH_TOKEN, then the config file.