# 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 ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.acecloud.ai/knowledge-base/cli/configuration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.