Configuration¶

grace-cli uses a YAML configuration file for environment profiles and defaults.

Config file location¶

The configuration file lives at:

~/.config/grace/config.yaml

This follows the XDG Base Directory Specification. Override the base with the XDG_CONFIG_HOME environment variable:

XDG_CONFIG_HOME=/custom/path grace auth status
# reads /custom/path/grace/config.yaml

File format¶

default_env: dev

environments:
  dev:
    url: http://localhost:41889
  staging:
    url: https://grace.staging.example.com
  prod:
    url: https://grace.production.example.com

Fields¶

Field	Type	Description
`default_env`	string	Environment used when `--env` is omitted. Defaults to `dev`.
`environments`	map	Named environment profiles. Each key is the environment name.
`environments.<name>.url`	string	Base URL of the Grace API server for this environment.

URL shorthand¶

For simple setups, you can use a shorthand where the value is just the URL string:

environments:
  dev: http://localhost:41889
  prod: https://grace.production.example.com

Both the shorthand and the full object format are equivalent.

Default behavior¶

If the config file doesn't exist, grace-cli operates with a single default environment:

default_env: dev
environments:
  dev:
    url: http://localhost:41889

This means grace auth login will target http://localhost:41889 without any configuration file needed — convenient for local development.

Environment selection¶

The active environment is resolved in this order:

--env flag — explicitly provided per command
default_env — from the config file
dev — hardcoded fallback

# Uses --env flag
grace device list --env prod

# Uses default_env from config
grace device list

# Override default globally for a session
grace --env staging device list

Environment variables¶

Variable	Effect
`XDG_CONFIG_HOME`	Override config file base directory
`NO_COLOR`	Disable all Rich formatting and colors (no-color.org)

Multiple environments in practice¶

A typical team setup with dev, staging, and production:

default_env: dev

environments:
  dev:
    url: http://localhost:41889
  staging:
    url: https://grace-staging.internal.example.com
  prod:
    url: https://grace.production.example.com

Then authenticate to each:

grace auth login --env dev
grace auth login --env staging
grace auth login --env prod

And use grace auth status to see all environments at a glance.