設定リファレンス

aqua はローカル設定ファイルと環境変数を組み合わせて使用します。このページでは、各設定ソースとそのスキーマについて説明します。

~/.aqua/credentials.json

1 つ以上の aqua サーバーの認証情報を保存します。このファイルは aqua-cli login および aqua-cli logout コマンドによって自動的に管理されます。

ファイルにはサーバー URL と認証トークンのマッピングが含まれます。このファイルを手動で編集する必要はありません。

保存場所： ~/.aqua/credentials.json（ユーザーホームディレクトリ）

.aqua/config.json

aqua-cli init によって作成されるプロジェクトレベルの設定です。このファイルはプロジェクトルートに配置され、通常はバージョン管理にコミットされます。

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

フィールド	型	説明
`server_url`	`string`	aqua バックエンドサーバーの URL です。
`project_key`	`string`	git リモート URL から導出されたプロジェクトの一意な識別子です。

.aqua/environments/<name>.json

環境ファイルは、テスト実行時に使用される変数、シークレット、プロキシ設定を定義します。各ファイルは名前付き環境を表します（例：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"
}

フィールド	型	説明
`variables`	`Record<string, string>`	実行時に利用可能なプレーンテキスト変数のキーバリューペアです。値に `{$ENV_VAR}` や `{$ENV_VAR:-default}` 構文を使用して、読み込み時に OS 環境変数の値を埋め込むことができます。
`secrets`	`Record<string, SecretRef>`	実行時に解決される名前付きシークレットです。シークレットタイプについては以下を参照してください。
`proxy`	`object`	（省略可） HTTP プロキシ設定です。TLS オプション（`ca_cert_path`、`proxy_ca_cert_path`、`reject_unauthorized`）を含む全フィールドは環境設定: プロキシを参照してください。
`notes`	`string`	（省略可）環境についての人間が読める説明です。

シークレットタイプ

シークレットは実行時に解決され、環境ファイルにプレーンテキストとして保存されることはありません。

環境変数：

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

指定した OS 環境変数から値を読み取ります。

GCP Secret Manager：

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

Google Cloud Secret Manager からシークレットを取得します。

環境変数

変数	説明
`AQUA_SERVER_URL`	aqua サーバーの URL をオーバーライドします。`.aqua/config.json` より優先されますが、`--server-url` CLI フラグによってオーバーライドされます。

追加の CA 証明書を信頼させる

aqua CLI が HTTPS で接続する際にカスタム CA を信頼させたい場合（プライベート CA で運用しているセルフホストの aqua サーバーや、TLS インスペクションを行う社内ネットワーク経由など）、Node.js 標準の以下の仕組みが利用できます。いずれも既定のトラストストアを置き換えず追加する形で動作します。

NODE_EXTRA_CA_CERTS=/path/to/ca.pem — PEM 形式のファイルに含まれる CA を信頼します。複数の証明書を 1 ファイルに連結することも可能です。
NODE_OPTIONS=--use-system-ca — OS の証明書ストアを信頼します。macOS では System / Login のキーチェーン、Windows では証明書ストア、Linux では OpenSSL 既定のバンドル（OS 固有のストアは参照されません）が対象です。Node.js 22.10 以降が必要です。

両方を併用することもできます。

MCP サーバーとして起動する場合

これらの環境変数は Node.js 起動時に読み込まれるため、CLI として直接呼び出した場合と MCP サーバーとして呼び出された場合で挙動は変わりません。コーディングエージェントが起動する Node.js 子プロセスまで環境変数が届いていることだけ確認してください。

最も確実なのは MCP サーバー設定の env フィールドで明示的に渡す方法です。GUI から起動するエージェントなどはシェルの環境を継承しないことがあるためです。

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

CLI から起動するエージェント（Claude Code、Gemini CLI など）の場合は、エージェント起動前にシェルで export しておく方法でも子プロセスに継承されます。