> For the complete documentation index, see [llms.txt](https://docs.acecloud.ai/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acecloud.ai/knowledge-base/cli/configuration.md). # Configuration The AceCloud CLI stores settings in `~/.ace/config.json`. This file is created automatically on first login. ## Config File ```json { "api_base_url": "https://customer.acecloud.ai/api/v1", "token": "eyJhbGciOiJIUzI1NiIsInR...", "region": "ap-south-noi-1", "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "api_key_id": "00000000-0000-0000-0000-000000000000", "api_key_secret": "EXAMPLE-secret-replace-with-your-own-do-not-use-this-value", "api_key_service_name": "terraform-prod" } ``` `api_base_url` is set automatically. You only need to manage `region` and `project_id`. The `token` *or* the three `api_key_*` fields hold your auth credentials — see the [Authentication](/knowledge-base/cli/authentication.md) page. API key fields take precedence over the JWT token when both are set. *** ## `ace configure` — Interactive Setup (Recommended) `ace configure` walks you through region, project, auth method, and credentials in one prompt sequence — modeled on `aws configure`. Existing values are shown as masked defaults in `[brackets]`. Press **Enter** to keep the existing value, or type a new value to overwrite. Secrets are never echoed to the terminal. ``` $ ace configure AceCloud Region [ap-south-noi-1]: AceCloud Project ID [a1b2c3d4-...]: Auth method (api-key/token) [api-key]: AceCloud API Key ID [None]: 00000000-0000-0000-0000-000000000000 AceCloud API Key Secret [None]: # hidden — typed input not shown AceCloud API Key Service Name [None]: terraform-prod Verifying credentials... OK (logged in as Jane Doe, jane.doe@example.com) Configuration saved to /Users/you/.ace/config.json. Try: ace instance list ``` If credentials don't verify, the file is **not** saved — re-run `ace configure`. ### Scripted variants (no prompts) For automation / one-off changes: ```bash ace configure set region ap-south-noi-1 ace configure set project_id a1b2c3d4-e5f6-7890-abcd-ef1234567890 ace configure set api_key_id 00000000-0000-0000-0000-000000000000 ace configure set api_key_secret EXAMPLE-secret-do-not-use ace configure set api_key_service_name terraform-prod ace configure get region # → ap-south-noi-1 ace configure list # → all values, secrets masked as "****" ``` Valid keys: `region`, `project_id`, `api_url`, `token`, `api_key_id`, `api_key_secret`, `api_key_service_name`. `ace configure list` output: ``` Config file: /Users/you/.ace/config.json api_key_id 00000000-0000-0000-0000-000000000000 api_key_secret ****0000 api_key_service_name terraform-prod api_url https://customer.acecloud.ai/api/v1 project_id a1b2c3d4-e5f6-7890-abcd-ef1234567890 region ap-south-noi-1 token (unset) ``` *** ## Commands ### `ace config show` (alias: `list`, `ls`) Display all config values. Secrets are masked as `****`. ```bash $ ace config show Config file: /Users/you/.ace/config.json api_key_id 00000000-0000-0000-0000-000000000000 api_key_secret ****0000 api_key_service_name terraform-prod api_url https://customer.acecloud.ai/api/v1 project_id a1b2c3d4-e5f6-7890-abcd-ef1234567890 region ap-south-noi-1 token (unset) ``` `ace config list` and `ace config ls` are aliases for `ace config show`. ### `ace config set` Set a config value. Accepted keys: `region`, `project` / `project_id`, `api_url` / `api_base_url`, `token`, `api_key_id`, `api_key_secret`, `api_key_service_name`. ```bash ace config set region ap-south-noi-1 ace config set project_id a1b2c3d4-e5f6-7890-abcd-ef1234567890 ``` `project` and `project_id` are interchangeable; same for `api_url` and `api_base_url`. ### `ace config get` Get a single value. Accepted keys: `region`, `project` / `project_id`, `api_url` / `api_base_url`, `token`, `api_key_id`, `api_key_secret`, `api_key_service_name`. ```bash ace config get region ace config get project_id ace config get api_base_url ``` ### `ace config use-project` Interactive project picker — fetches your projects and lets you select one. ```bash $ ace config use-project ? Select a project: > My Production Project (ap-south-noi-1) Staging Environment (ap-south-noi-1) Switched to project: My Production Project (region: ap-south-noi-1) ``` **Alias:** `ace config switch-project` *** ## Environment Variables Override config values without modifying the file: | Variable | Overrides | Description | | -------------------------- | ---------------------- | ------------------------------------ | | `ACE_TOKEN` | `token` | JWT token (\~3 h expiry) | | `ACE_PROJECT_ID` | `project_id` | Project ID | | `ACE_REGION` | `region` | Region | | `ACE_API_KEY_ID` | `api_key_id` | API key ID (preferred for CI) | | `ACE_API_KEY_SECRET` | `api_key_secret` | API key secret (preferred for CI) | | `ACE_API_KEY_SERVICE_NAME` | `api_key_service_name` | Service name registered with the key | When `ACE_API_KEY_ID` + `ACE_API_KEY_SECRET` are both set, the CLI sends the `X-Ace-Api-Key` header instead of `Authorization: Bearer` — JWT envvars are ignored. ```bash # Override project for one command ACE_PROJECT_ID=other-project ace instance list # CI/CD — API key (recommended) export ACE_API_KEY_ID="00000000-0000-0000-0000-000000000000" export ACE_API_KEY_SECRET="EXAMPLE-secret-do-not-use" export ACE_API_KEY_SERVICE_NAME="ci-pipeline" export ACE_PROJECT_ID="your-project" export ACE_REGION="ap-south-noi-1" ace instance list -o json # CI/CD — JWT (legacy, ~3 h expiry) export ACE_TOKEN="your-token" ace instance list -o json ``` *** ## Precedence ``` CLI flag (--project, --region) > Environment variable > Config file > Default ``` Example: ```bash # Config has region=ap-south-noi-1, but this uses us-east-1 ace instance list --region us-east-1 ``` *** ## Reset Delete config and start fresh: ```bash rm -rf ~/.ace ace configure # interactive setup # or ace auth login-token --token # JWT only # or ace auth login-api-key --key id.secret \ --service-name svc # API key only ```