Docs/CLI/Authentication

Authentication

One CLI, many environments. Cloud and every self-hosted cluster side by side.

The CLI stores credentials per named environment. One host, many environments — cloud and several self-hosted clusters can be configured side by side, and you switch between them with a flag or an env var.

Log in (cloud)

bash
wordcab login
# opens a browser, completes an OAuth flow, caches the token in ~/.wordcab/config.yml under the "default" environment

Non-interactive (CI)

bash
# Simpler: export the API key
export WORDCAB_API_KEY=wc_live_xxxxxxxx

# Or authenticate programmatically
wordcab login --api-key $WORDCAB_API_KEY --env default

Add a self-hosted environment

bash
wordcab login \\
  --env on-prem \\
  --base-url https://wordcab.apps.example.com \\
  --api-key wc_sh_xxxxxxxx

Switch environments

bash
wordcab --env on-prem calls list    # per-command override
export WORDCAB_ENV=on-prem           # per-shell
wordcab env set on-prem              # per-host default

Inspect credentials

bash
wordcab env list                      # which environments are configured
wordcab whoami                        # identity, key prefix, scopes, current environment
wordcab ping                          # tests the network + auth path end to end

Log out

bash
wordcab logout                        # current environment
wordcab logout --env on-prem          # specific environment
wordcab logout --all                  # drop every cached credential

Configuration file

All config lives in ~/.wordcab/config.yml. It is YAML, safe to commit per-user, and can be overridden with --config /path/to/other.yml.

yaml
current_environment: default

environments:
  default:
    base_url: https://api.wordcab.com
    api_key_ref: $WORDCAB_API_KEY           # resolve at runtime
  on-prem:
    base_url: https://wordcab.apps.example.com
    api_key_file: ~/.wordcab/onprem.key
    ca_bundle: /etc/ssl/certs/example-root.crt
  staging:
    base_url: https://wordcab-staging.apps.example.com
    api_key_file: ~/.wordcab/staging.key
Credential helpers

On production hosts, prefer api_key_file (mode 0600) or a credential helper (Vault, AWS Secrets Manager, keychain) over plaintext. The CLI shells out to exec entries when present — see wordcab env config --help.