M

# Maeris CLI Reference

Complete command reference · resource-first grammar · `maeris <resource> <action>`

Auth & App Management

Command | Required Flags | Optional Flags | Description
--- | --- | --- | ---
maeris auth login | — | --token/-t TOKEN | OAuth or direct token auth, stored per-repo
maeris auth logout | — | — | Sign out and remove stored credentials
maeris auth status | — | — | Show auth status for the current repository
maeris app init | — | — | Register MCP server, writes `.mcp.json` to cwd
maeris app create | — | --name/-n NAME --url/-u URL | Create new application and set as active
maeris app switch | — | --name/-n NAME --url/-u URL | Switch active application (interactive or flags)
maeris app plan | — | — | Show active subscription plan for current app
maeris app link PATH | PATH | --label/-l LABEL | Link another repo as context source for test generation
maeris app unlink PATH_OR_LABEL | PATH_OR_LABEL | — | Remove a linked repository
maeris app links | — | — | List all linked context repositories
maeris ui tidy | — | --name ATTR --target/-t DIR --dry-run/-d --yes/-y | Inject `data-automation-id` attributes onto interactable elements
maeris config set KEY VALUE | KEY VALUE | — | Set persistent CLI config (stored in `~/.maeris/.env`)
maeris config get KEY | KEY | — | Get a CLI config value
maeris config list | — | — | List all persistent CLI config values
maeris config completions | — | --install/-i | Set up shell auto-completion (bash / zsh / fish)

Test Management

Command | Required Flags | Optional Flags | Description
--- | --- | --- | ---
maeris test generate [FLOW_DESC] | — | --target/-t DIR --folder/-f FOLDER --no-run/-N --model/-m MODEL | AI-generate, run & push Playwright tests. Default model: `claude-sonnet-4-6`
maeris test run | — | --smoke --regression/-r --all/-a --name/-n NAME --folder/-f FOLDER --type TYPE --local --browser BROWSER --execution-id/-e ID | Run testcases (cloud or local Playwright). Prints results table
maeris test list | — | --smoke --regression --all --origin ORIGIN --name/-n NAME --search/-q QUERY --test-type TYPE --include-id --include-name --include-origin --include-path | List testcases with field selection
maeris test import [PATHS] | — | --framework/-F auto|playwright|cypress|selenium --base-url/-u URL --test-folder FOLDER --label/-l LABELS --page-name NAME | Import Playwright / Cypress / Selenium scripts as manual testcases
maeris test delete | — | --smoke --regression/-r --all/-a --origin ORIGIN --name/-n NAME | Delete testcases (interactive menu or flags)
maeris test fix | — | --name/-n NAME --folder/-f FOLDER --edit/-e --source/-s SOURCE | Claude auto-fixes stale selectors / steps; `--edit` for interactive mode
maeris test recalibrate | — | --source/-s SOURCE --name/-n NAME --folder/-f FOLDER --dry-run/-d --model/-m MODEL | Scan UI source and update steps to match current codebase (in-place)
maeris folder create | --name/-n NAME | --parent-name PARENT | Create a testcase folder / group
maeris folder list | — | --name/-n NAME --id --parent-id | List testcase folders
maeris folder delete | — | --name/-n FILTER --name-prefix PREFIX --parent-name PARENT --parent-name-prefix PREFIX --all --yes/-y | Delete testcase folders

APIs

Command | Required Flags | Optional Flags | Description
--- | --- | --- | ---
maeris api list | — | --collection/-c COLLECTION | List all APIs, optionally filtered by collection
maeris api get API | API | — | Get API by name or ID
maeris api create | --name/-n NAME --method/-m METHOD --url/-u URL | --payload/-p PAYLOAD --collection/-c COLLECTION | Create an API entry
maeris api bulk | --apis JSON_ARRAY | — | Bulk-create multiple APIs at once
maeris api import | --from SOURCE_FILE | --collection COLLECTION --model MODEL | Extract API definitions from source file via Claude
maeris api update API | API --data JSON | — | Update API with JSON payload
maeris api clone API | API | --new-name NAME | Duplicate an API entry
maeris api move API | API --to-collection/-c COLLECTION | — | Move API to another collection
maeris api delete API | API | — | Delete API by name or ID
maeris api param add API | API | --headers JSON --params JSON | Add param / header records to an API
maeris api param update API | API --field-name NAME --field-value VALUE --field-type param|header | — | Update a specific param or header on an API
maeris api param delete API | API --field-name NAME | — | Delete a param or header from an API

Collections

Command | Required Flags | Optional Flags | Description
--- | --- | --- | ---
maeris collection list | — | — | List all collections
maeris collection get COLLECTION | COLLECTION | — | Get collection details by name or ID
maeris collection subs COLLECTION | COLLECTION | — | List subcollections of a collection
maeris collection create | --name/-n NAME | --parent/-p PARENT | Create a collection
maeris collection rename COLLECTION | COLLECTION --name NAME | — | Rename a collection
maeris collection clone COLLECTION | COLLECTION --name/-n NAME | — | Copy a collection to a new name
maeris collection delete COLLECTION | COLLECTION | — | Delete a collection by name or ID

Environments

Command | Required Flags | Optional Flags | Description
--- | --- | --- | ---
maeris env list | — | — | List all environments
maeris env create | --name/-n NAME | — | Create an environment
maeris env rename ENV | ENV --name NAME | — | Rename an environment
maeris env delete ENV | ENV | — | Delete an environment
maeris env data list ENV | ENV | — | Get key/value fields for an environment
maeris env data add ENV | ENV --fields JSON_ARRAY | — | Add key/value fields to environment
maeris env data update ENV | ENV --field-name NAME --field-value VALUE | — | Update an environment field value
maeris env data delete ENV | ENV --field-name NAME | — | Delete a field from an environment

Flows

Command | Required Flags | Optional Flags | Description
--- | --- | --- | ---
maeris flow list | — | — | List all API flows
maeris flow create | --name NAME | — | Create an API flow
maeris flow rename FLOW | FLOW --name NAME | — | Rename a flow
maeris flow run FLOW | FLOW --env/-e ENV | --json | Run a flow against an environment
maeris flow delete FLOW | FLOW | — | Delete a flow by name or ID
maeris flow map get FLOW | FLOW | — | Get the flow map (step sequence) for a flow
maeris flow map set FLOW | FLOW --flow-map JSON_ARRAY | — | Set / replace the flow map for a flow
maeris flow param get FLOW | FLOW | — | Get params for a flow
maeris flow param add FLOW | FLOW --params JSON_ARRAY | — | Add params to a flow
maeris flow param update FLOW | FLOW --params JSON_ARRAY | — | Update flow params
maeris flow param delete FLOW | FLOW | — | Delete params for a flow

Assertions

Command | Required Flags | Optional Flags | Description
--- | --- | --- | ---
maeris assertion list | — | --api/-a API | List assertions, optionally filtered by API
maeris assertion create | --api API --nature NATURE --type TYPE --value JSON | — | Create an API response assertion
maeris assertion update ID | ASSERTION_ID --value JSON | — | Update an assertion's value
maeris assertion delete ID | ASSERTION_ID | — | Delete an assertion

Coverage

Command | Required Flags | Optional Flags | Description / Output
--- | --- | --- | ---
maeris coverage ui | — | --source/-s SOURCE --json/-j | UI test coverage grouped by area / functionality. Shows covered, uncovered, and orphaned tests
maeris coverage api | — | --source/-s SOURCE --json/-j | API flow coverage. Table: endpoint, in_maeris, in_flow, flows. Warns on unregistered routes

Scanning

Command | Required Flags | Optional Flags | Description / Depth Presets
--- | --- | --- | ---
maeris scan security | — | --source/-s SOURCE --quick --deep --profile PROFILE --model/-m MODEL | LLM-guided static security scan. default OWASP Top 10, 5 files/batch --quick 3 files/batch --deep 600+ checks, 10 files/batch
maeris scan api | — | --source/-s SOURCE --quick --deep --project-name NAME --model/-m MODEL | Extract API definitions from codebase via Claude. Default collection: current directory name

Reports

Command | Required Flags | Optional Flags | Description
--- | --- | --- | ---
maeris report tests | — | --format json|md|html --output/-o FILE --folder/-f FOLDER --name/-n NAME | Export all testcases report. Default format: `json`
maeris report coverage | — | --format json|md|html --source/-s SOURCE --output/-o FILE | Export UI + API coverage report. Default format: `json`
maeris report security | — | --format json|md|html --output/-o FILE | Export latest security scan results. Run `maeris scan security` first

Drift Detection & Repair

Command | Required Flags | Optional Flags | Description
--- | --- | --- | ---
maeris repair ui | — | --source/-s SOURCE --model/-m MODEL --dry-run --yes/-y --json | Phase 1 (deterministic): scan testcase selectors vs source. Phase 2 (AI): Claude proposes replacement selectors
maeris repair api | — | --source/-s SOURCE --model/-m MODEL --dry-run --yes/-y --json | Phase 1 (deterministic): diff backend routes vs Maeris registry. Phase 2 (AI): Claude recommends deleting or updating stale entries
maeris repair flow | — | --model/-m MODEL --dry-run --yes/-y --json | Phase 1 (deterministic): check flow steps vs API registry. Phase 2 (AI): Claude proposes replacement APIs for stale steps
maeris repair contract | — | --source/-s SOURCE --model/-m MODEL --dry-run --yes/-y --json | Full cross-domain repair: runs `repair ui` + `repair api` + `repair flow` in sequence

Baseline Test Generation

Command | Required Flags | Optional Flags | Description
--- | --- | --- | ---
maeris baseline generate | --source/-s SOURCE | --url/-u URL --model/-m MODEL --browser/-b BROWSER --folder FOLDER --dry-run --json --verbose/-v | Full pipeline: 1. Deterministic page/route discovery from source 2. Claude generates test steps (compact page summaries, not full source) 3. Local Playwright execution — 3 consecutive passes required 4. Max 1 AI repair attempt per failing test 5. Push stable tests to Maeris (`--dry-run` skips push) Output: `✓ N stable · ✗ N discarded (unstable)`

CI Quality Gate

Command | Required Flags | Optional Flags | Description
--- | --- | --- | ---
maeris ci | — | --scan/--no-scan --coverage/--no-coverage --run/--no-run --folder/-f FOLDER --fail-below N --source/-s SOURCE --model/-m MODEL --contract-check/--no-contract-check --json | Compound quality gate for CI pipelines. Defaults: scan=✓, coverage=✓, run=✗, contract-check=✗ `--contract-check` runs deterministic drift detection (UI + API + flows) — never auto-repairs, exits 1 if drift found `--fail-below N` exits 1 if coverage < N% Exit codes: `0` = all pass `1` = gate failure

Error & Status Messages

Context | Message | Notes
--- | --- | ---
Not authenticated | ✗ Not authenticated. Run 'maeris auth login' first. | Emitted before any API call when no token is found
Token expired | ✗ Token expired. Run 'maeris auth login' to re-authenticate. | Prompts re-login; credentials are per-repo
Claude CLI missing | ✗ Claude Code CLI not found on PATH. | Required by `test generate`, `test fix`, `test recalibrate`, `repair *`, `baseline generate`
Playwright missing | ✗ Playwright is not installed. | Required by `test run --local` and `baseline generate`. Install: `pip install playwright && python -m playwright install chromium`
Unknown command | Error: No such command '{cmd}'. Did you mean '{closest}'? | Closest match via `difflib.get_close_matches()` on all group commands
API resolve failure | ✗ Could not find API: '{name}' | Resolver searches by name then ID
Source path missing | ✗ Source path does not exist: {path} | Emitted by `baseline generate`, `repair ui`, `coverage ui`
Drift found (CI) | ✗ N drift issue(s) found. | Emitted by `ci --contract-check`; exits 1. Run `maeris repair contract` to fix
Unstable baseline tests | ✗ N test(s) discarded (unstable) | Emitted by `baseline generate` when tests fail 3-pass gate; exits 1
Dry run mode | --dry-run: skipping Maeris push. | Emitted by `baseline generate`, `repair *`, `test recalibrate` with `--dry-run`
Coverage warning | Warning: endpoints not registered in Maeris | Emitted by `coverage api` when routes exist only in source

Required Required argument or flag Optional Optional flag or preset label --flag Optional CLI flag ✗ Error Error or failure message Info Status or info output
Maeris CLI Reference · Generated 2026-03-04 · Resource-first grammar: `maeris <resource> <action>` · To save as PDF: browser Print → Save as PDF