Configuration

The AceCloud CLI stores settings in ~/.ace/config.json. This file is created automatically on first login.

Config File

{
  "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 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, [e-mail])

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:

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 "****<last4>"

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

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

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.

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.

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

# 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:

# 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:

rm -rf ~/.ace
ace configure                                   # interactive setup
# or
ace auth login-token --token <new-token>        # JWT only
# or
ace auth login-api-key --key id.secret \
                       --service-name svc       # API key only