Authentication And Environments

Login flow

gaard login starts a browser-based sign-in flow, creates a personal access token, and stores that token in the CLI config.

gaard login

If there is no current context and --api is omitted, the CLI defaults to:

https://app.gaard.ai/

You can still target a different environment or assign a context name explicitly:

gaard login --api https://staging.gaard.ai --name staging

If --name is omitted, the CLI derives the context name from the API hostname when possible.

When the command starts, it opens the verification URL in your browser if possible. If not, it prints the URL in the terminal so you can open it manually.

Config file

By default, the CLI stores configuration at:

~/.gaard/config.yaml

You can override the location with the GAARD_CONFIG environment variable:

GAARD_CONFIG=/tmp/gaard.yaml gaard ctx list

Contexts

Contexts let you keep separate API URLs, tokens, and default tenants for different environments such as local, staging, and production.

List contexts:

gaard ctx list

Add a context without logging in yet:

gaard ctx add staging --api https://staging.gaard.ai

Switch the active context:

gaard ctx use staging

Remove a context:

gaard ctx remove staging

Tenant selection

Tenant resolution follows this order:

1. --tenant
2. The context’s session-tenant
3. The context’s default tenant

If none is set, tenant-aware commands return an error telling you to select a tenant or pass --tenant.

Super users can switch the session tenant without re-authenticating:

gaard tenant list
gaard tenant use acme_prod
gaard tenant clear

For one-off commands, it is often simpler to override the tenant inline:

gaard --tenant acme_prod whoami

Logout

gaard logout removes the stored token from the current context:

gaard logout

The context remains in the config file, but authenticated commands will fail until you log in again.