Authentication

grace-cli stores credentials per environment so you never need .env files or copy-paste tokens between sessions.

How it works

grace auth login --env prod
  ↓
  Interactive prompt (username + password)
  ↓
  Validates against the Grace API server
  ↓
  Saves to OS keyring (or local file fallback)

Subsequent commands read stored credentials automatically. No re-authentication needed until you run grace auth logout.

Credential backends

grace-cli tries the OS keyring first, falling back to a local file on headless systems.

Backend	When used	Storage
OS Keyring	Desktop Linux (GNOME Keyring, KWallet), macOS Keychain, Windows Credential Manager	OS-managed encrypted store
JSON File	Headless Linux, containers, CI runners (keyring unavailable)	~/.config/grace/credentials.json with 0600 permissions

Checking your backend

Run grace auth status — the Backend column shows which storage is active.

Commands

grace auth login

Store credentials for an environment:

grace auth login --env prod

Logging in to prod (https://grace.production.example.com)
Username: operator
Password: ********
OK: Credentials saved for 'prod' (backend: SecretService)

The command validates credentials by connecting to the API before saving. If authentication fails, nothing is stored.

Warning

The environment must be defined in your config file before you can log in.

grace auth logout

Remove stored credentials for an environment:

grace auth logout --env prod

OK: Credentials removed for 'prod'.

grace auth status

Show credential and connectivity status for all configured environments:

grace auth status

         Authentication Status
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Environment   ┃ URL                     ┃ Backend       ┃ Username ┃ Connectivity ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ dev (active)  │ http://localhost:41889  │ SecretService │ a***n    │ reachable    │
│ staging       │ https://grace-stag...   │ SecretService │ o******r │ reachable    │
│ prod          │ https://grace.prod...   │ SecretService │ none     │ no creds     │
└───────────────┴─────────────────────────┴───────────────┴──────────┴──────────────┘

• Username is masked for security (first and last character visible)
• Connectivity is checked live against each environment's API
• (active) marks the currently selected default environment

CI and headless usage

In CI pipelines or containers where no keyring daemon is available, grace-cli automatically falls back to the JSON file backend.

A typical CI pattern:

# Write config
mkdir -p ~/.config/grace
cat > ~/.config/grace/config.yaml <<EOF
default_env: prod
environments:
  prod:
    url: https://grace.production.example.com
EOF

# Write credentials directly (skip interactive login)
cat > ~/.config/grace/credentials.json <<EOF
{
  "prod": {
    "username": "$GRACE_USERNAME",
    "password": "$GRACE_PASSWORD"
  }
}
EOF
chmod 600 ~/.config/grace/credentials.json

# Now commands work non-interactively
grace device list --output json

Security

In CI, use secret variables ($GRACE_USERNAME, $GRACE_PASSWORD) rather than hardcoding credentials. The credentials file is created at runtime and discarded when the container exits.