ambrogio

Run AI-powered scenarios from your terminal or coding agent.

Ambrogio is the product reliability layer — define scenarios in natural language, and Ambrogio runs them against your app using real browsers in the cloud. This CLI lets you trigger those scenarios from anywhere: your terminal, a CI pipeline, or a coding agent like Claude Code, Cursor, or Devin.

Install

npm install -g ambrogio

Or run directly:

npx ambrogio run --product 42 --url https://staging.example.com

Setup

ambrogio set-api-key <your-api-key>
ambrogio select-product

Get your API key from app.ambrogio.tech in your product settings. select-product fetches your products and lets you pick one (auto-selects if you only have one).

Once configured, just run:

ambrogio run --url https://staging.example.com

Usage

Run against a URL

ambrogio run --url https://staging.example.com

Run against localhost

Scenarios run in cloud browsers that can't reach localhost. Pass --local and the CLI creates a tunnel automatically via cloudflared:

brew install cloudflared   # one-time setup
ambrogio run --local 3000

Override credentials

Pass runtime credentials without changing your product settings:

ambrogio run --url https://staging.example.com \
  --cred "[email protected]" \
  --cred "PASSWORD=secret123"

Run a specific section or scenario

# Only run scenarios in the "checkout" section
ambrogio run --section checkout --url https://staging.example.com

# Run specific scenario IDs
ambrogio run --scenario 12 --scenario 34 --url https://staging.example.com

List existing scenarios

Before running or writing new scenarios, list what's already covered for your product:

ambrogio list                        # active + draft + planned (default)
ambrogio list --section checkout     # filter by section
ambrogio list --status draft         # only drafts awaiting review
ambrogio list --json                 # machine-readable (default in non-TTY)

Coding agents should call list first to find scenarios touching the area they just changed, then run only those IDs for a fast smoke test.

Verify a new feature

A coding agent just built something? Describe what it should do and Ambrogio verifies it in a real browser. The scenario is saved as a draft for human review before entering the regression suite.

ambrogio verify --intent "User can add item to cart and complete checkout" --local 3000

Run options

| Flag | Description | |------|-------------| | --product, -p <id> | Product ID (flag > AMBROGIO_PRODUCT_ID env > config) | | --url <base_url> | Base URL to run against | | --local <port> | Run against localhost:port | | --cred KEY=VALUE | Override a credential (repeatable) | | --api-key <key> | API key (overrides env and config) | | --section <name> | Run scenarios in a specific section only | | --scenario <id> | Run a specific scenario ID (repeatable) |

List options

| Flag | Description | |------|-------------| | --product, -p <id> | Product ID (flag > AMBROGIO_PRODUCT_ID env > config) | | --status <name> | active, draft, planned, creating, failed, or all. Default: active,draft,planned. Comma-separated list accepted. | | --section <name> | Filter by section | | --source <name> | Filter by source (e.g. agent, user) | | --json | Force JSON output (default in non-TTY) | | --api-key <key> | API key (overrides env and config) |

Verify options

| Flag | Description | |------|-------------| | --product, -p <id> | Product ID (flag > AMBROGIO_PRODUCT_ID env > config) | | --intent, -i <text> | What to verify (natural language description) | | --url <base_url> | Base URL to run against | | --local <port> | Run against localhost:port | | --cred KEY=VALUE | Override a credential (repeatable) | | --api-key <key> | API key (overrides env and config) |

Configuration

Settings are stored in ~/.ambrogio/config.json:

ambrogio set-api-key ambra_xxx   # save API key
ambrogio select-product          # pick your product interactively

Both values can also be set via environment variables (AMBROGIO_API_KEY, AMBROGIO_PRODUCT_ID) or flags (--api-key, --product). Flags take priority over env vars, which take priority over the config file.

Output

In a terminal — pretty output with spinners and pass/fail indicators.

Piped or in a CI/agent context — structured JSON to stdout.

Exit codes — 0 if all scenarios pass, 1 if any scenario fails.

Use with coding agents

Agents like Claude Code should treat Ambrogio as the default verification step after any change. Use it proactively — not only when asked:

export AMBROGIO_API_KEY=ambra_xxx
export AMBROGIO_PRODUCT_ID=42

# 1. List existing scenarios to find what covers the area you changed
ambrogio list --json

# 2. Smoke-test affected scenarios first (fast feedback)
ambrogio run --local 3000 --scenario 12 --scenario 34
#    or by section:
ambrogio run --local 3000 --section checkout

# 3. Verify any genuinely new behavior and save as a draft scenario
ambrogio verify --intent "User can add item to cart and checkout" --local 3000

# 4. Run the full suite before declaring the task done
ambrogio run --local 3000

list tells you what's covered. run proves it still works. verify grows the suite. Together they form the full loop: build → list → smoke → verify → regression.

The JSON output and exit code give the agent a clear signal to continue or fix. Treat a non-zero exit as a blocker.

Links

• Website
• Dashboard