CLI

The nodemantis command line ships inside the npm package node-mantis and exposes the full agent surface from a terminal: run a browser goal, retrieve typed data from a page, and set up or diagnose an installation. Installing the package puts two equivalent commands on your PATH, 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 (model tiers, budgets, retrieval statuses and result fields) is defined once in the API reference.

Install

A global npm install (or Homebrew on macOS and Linux) is all the CLI needs — the package carries the command line, the SDK, and the compiled agent runtime for your platform, so there is nothing else to set up and no project required. For a zero-install run, call the package through npx using the package name node-mantis — the nodemantis bin alias only exists after the package is installed, so only the package-name form auto-installs.

npm install -g node-mantis@0.1.0-alpha.9

# or via Homebrew
brew install node-mantis/tap/nodemantis

# zero-install: invoke via the npm package name
npx node-mantis@0.1.0-alpha.9 doctor

python -m pip install "node-mantis[browser]==0.1.0a9"

# isolated install
pipx install "node-mantis[browser]==0.1.0a9"

The Python package installs a nodemantis command too, but it covers only the setup verbs — configure, doctor, install-browser, and smoke. run and retrieve are available only from the npm CLI. When both packages are installed, the first nodemantis on your PATH wins.

Quickstart

Store a key, install a browser, verify the environment, 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 install-browser --browser chrome
nodemantis doctor
nodemantis run "Open the pricing page and report the Pro plan price." \
  --url https://example.com

nodemantis run

Runs a multi-step browser goal, narrating each iteration on stderr while it works. Pass --schema or --retrieval to get a grounded, typed result on top of the goal outcome.

nodemantis run "Find a quiet double room for two nights and open checkout." \
  --url https://example.com --max-iterations 20 --max-cost 0.50

nodemantis retrieve

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 "List the plan names and monthly prices." \
  --url https://example.com --schema plans.schema.json --json

nodemantis configure

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.

nodemantis doctor

Prints an environment diagnosis: which source the API key resolves from (with the key masked), the platform, the agent-engine handshake, and browser availability. It works offline — no goal is run.

nodemantis install-browser

Installs Google Chrome (or Playwright Chromium) for the agent to drive. Package installation never downloads a browser silently — this command is the explicit step.

nodemantis smoke

End-to-end installation check: a hosted-API preflight, a browser test against a local fixture page, and an engine boundary check. Run it after installing on a new workstation or CI image.

Live narration

While runworks, each agent iteration is narrated on stderr using the model's own reasoning for the step it is about to take:

$ nodemantis run "Submit the contact form" --url https://example.com
[1/20] The contact form is empty — type_text("Name", "Ada Lovelace")
[2/20] Name is set, the message is next — type_text("Message", "Hello!")
[3/20] All input fields are filled — click("Submit")

Narration goes to stderr only, so it never pollutes stdout — piping the command's output stays safe even without --json. --quiet suppresses it.

JSON output

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 "What is the cheapest plan?" \
  --url https://example.com --json | jq .status

Exit codes

• 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.

Configuration file

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.

CLI and SDK

The CLI covers running goals and retrieving data. extract, check, and step are SDK-only — use the TypeScript SDK when you need page extraction, page-state checks, or bounded single instructions.