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.
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.