CLI Reference

The aqua CLI (aqua-cli) provides commands for authentication, project setup, test execution, and browser recording. Run any command with npx @aquaqa/cli.

aqua-cli login

aqua-cli login [--server-url <url>] [--force]

Authenticate with the aqua server. Opens your default browser to complete the authentication flow. On success, credentials are saved to ~/.aqua/credentials.json.

Option	Description
--server-url <url>	The aqua server URL to authenticate against. Required for self-hosted environments. Defaults to https://app.aquaqa.com.
--force	Re-authenticate even if valid credentials already exist.

CI/CD environments

For CI/CD environments where browser-based login is not available, set the AQUA_API_KEY environment variable instead. See Configuration: Environment Variables.

aqua-cli logout

aqua-cli logout

Remove saved credentials for the server.

aqua-cli init

aqua-cli init [--server-url <url>]

Initialize project configuration. Detects the git remote URL to derive a project_key, lets you select the organization and project, and creates a .aqua/config.json file in the current directory.

Option	Description
--server-url <url>	The aqua server URL to associate with this project. Required for self-hosted environments. Defaults to https://app.aquaqa.com.

aqua-cli whoami

aqua-cli whoami

Display information about the currently authenticated user, including user ID, email address, and display name.

aqua-cli execute

aqua-cli execute <qa_plan_id> [--env <name>] [--plan-version <n>] [--var key=value]

Execute a QA plan directly from the command line without going through the MCP server.

Option	Description
<qa_plan_id>	(required) The ID of the QA plan to execute.
--env <name>	Load environment variables from .aqua/environments/<name>.json.
--plan-version <n>	Execute a specific plan version. Defaults to the latest version.
--var key=value	Override a variable value. Can be specified multiple times.

aqua-cli record

aqua-cli record [url]

Record browser actions using Playwright codegen. Opens an interactive browser window where your interactions are captured. When the browser is closed, the recorded actions are output as a BrowserStep[] JSON array.

Option	Description
[url]	(optional) The URL to navigate to when the browser opens.

aqua-cli web

aqua-cli web

Open the aqua web UI in your default browser.

aqua-cli mcp-server

aqua-cli mcp-server

Start the MCP (Model Context Protocol) server. This enables AI agents such as Claude Code, Gemini CLI, OpenCode, and Cursor to interact with aqua programmatically.

Authentication is resolved in the following order of precedence:

1. AQUA_API_KEY environment variable
2. ~/.aqua/credentials.json (managed by aqua-cli login)

The server URL is resolved in the following order of precedence:

1. AQUA_SERVER_URL environment variable
2. .aqua/config.json in the current project
3. https://app.aquaqa.com (default)