Configuration Reference

aqua uses a combination of local configuration files and environment variables. This page documents each configuration source and its schema.

~/.aqua/credentials.json

Stores authentication credentials for one or more aqua servers. This file is managed automatically by the aqua-cli login and aqua-cli logout commands.

The file contains a map of server URLs to their authentication tokens. You should not edit this file manually.

If the AQUA_API_KEY environment variable is set, it takes precedence over the credentials file. See Environment Variables below.

Location: ~/.aqua/credentials.json (user home directory)

.aqua/config.json

Project-level configuration created by aqua-cli init. This file lives in your project root and is typically committed to version control.

{
  "server_url": "https://app.aquaqa.com",
  "project_key": "github.com/owner/repo"
}

Field	Type	Description
server_url	string	The URL of the aqua backend server.
project_key	string	A unique identifier for the project, derived from the git remote URL.

.aqua/environments/<name>.json

Environment files define variables, secrets, and proxy settings for test execution. Each file represents a named environment (e.g., staging.json, production.json).

{
  "variables": {
    "base_url": "https://staging.example.com",
    "api_version": "v2"
  },
  "secrets": {
    "api_key": {
      "type": "env",
      "key": "STAGING_API_KEY"
    },
    "db_password": {
      "type": "gcp_secret",
      "project": "my-project",
      "secret": "db-password",
      "version": "latest"
    }
  },
  "proxy": {
    "server": "http://proxy.internal:8080",
    "ca_cert_path": "/path/to/ca.pem",
    "reject_unauthorized": false
  },
  "notes": "Staging environment for integration tests"
}

Field	Type	Description
variables	Record<string, string>	Key-value pairs of plain-text variables available during execution. Values support {$ENV_VAR} and {$ENV_VAR:-default} syntax for OS environment variable interpolation at load time.
secrets	Record<string, SecretRef>	Named secrets resolved at execution time. See secret types below.
proxy	object	(optional) HTTP proxy configuration. See Environments: Proxy for all fields including TLS options (ca_cert_path, proxy_ca_cert_path, reject_unauthorized).
notes	string	(optional) A human-readable description of the environment.

Secret Types

Secrets are resolved at execution time and never stored in plain text in the environment file.

Environment variable:

{ "type": "env", "key": "ENV_VAR_NAME" }

Reads the value from the specified OS environment variable.

GCP Secret Manager:

{ "type": "gcp_secret", "project": "gcp-project-id", "secret": "secret-name", "version": "latest" }

Fetches the secret from Google Cloud Secret Manager.

Environment Variables

Variable	Description
AQUA_API_KEY	API key for authentication. Takes precedence over ~/.aqua/credentials.json. Useful for CI/CD environments where browser-based login is not available.
AQUA_SERVER_URL	Override the aqua server URL. Takes precedence over .aqua/config.json but is overridden by the --server-url CLI flag.

Trusting Additional CA Certificates

If the aqua CLI’s outbound HTTPS connections need to trust a custom CA (e.g., a self-hosted aqua server with a private CA, or a corporate TLS-inspecting network), use the standard Node.js mechanisms below. These add to — they do not replace — the default trust store.

• NODE_EXTRA_CA_CERTS=/path/to/ca.pem — Trust the CAs in a PEM file. Multiple certificates can be concatenated into a single file.
• NODE_OPTIONS=--use-system-ca — Trust the OS certificate store. On macOS this reads the System/Login Keychain; on Windows it reads the Windows certificate store; on Linux it falls back to the OpenSSL default bundle. Requires Node.js 22.10 or later.

Both can be combined.

When running as an MCP server

The variables above are read at Node.js startup and apply identically whether the CLI is invoked directly or launched as an MCP server. The only thing to ensure is that the variables actually reach the Node subprocess spawned by the coding agent.

The most reliable way is to set them in the MCP server config’s env field, since some agents (especially GUI-launched ones) do not inherit your shell environment:

{
  "mcpServers": {
    "aqua": {
      "command": "npx",
      "args": ["@aquaqa/cli", "mcp-server"],
      "env": {
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}

For CLI-launched agents (Claude Code, Gemini CLI, etc.), exporting the variables in the shell before starting the agent also works, since the child process inherits the parent’s environment.