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