CLI Authentication

The GuaraCloud CLI supports two authentication methods: browser-based OAuth login for interactive use, and API keys for scripts and CI/CD pipelines.

Browser login

The simplest way to authenticate is with the browser login flow:

guara login

This opens your default browser to the GuaraCloud login page. After you sign in, the CLI receives an API key automatically and stores it securely in your system keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service). If the keychain is unavailable, the key is stored in a local config file.

$ guara login
Opening browser to authenticate...
  https://api.guaracloud.com/v1/auth/cli-login?callback=...
✓ Authenticated as [email protected]
  API key stored in system keychain.

You can force the browser flow explicitly with:

guara login --browser

API key login

You can also authenticate directly with an API key. Generate an API key in your account settings, then:

guara login --api-key gk_live_abc123def456

The CLI validates the key by calling the API, then stores it in your system keychain.

Environment variables

For CI/CD pipelines and non-interactive environments, use environment variables instead of guara login:

Variable	Description
GUARA_API_KEY	API key for authentication. When set, the CLI skips the keychain lookup entirely.
GUARA_API_URL	Override the API base URL. Useful for pointing to a staging environment.
GUARA_PROJECT	Default project slug. Equivalent to --project.
GUARA_SERVICE	Default service slug. Equivalent to --service.

# Authenticate and deploy in a single line
GUARA_API_KEY=gk_live_xxxxx guara deploy --project my-project --service my-api # gitleaks:allow

Using a staging environment

To point the CLI at a staging instance of GuaraCloud:

# Via environment variable
export GUARA_API_URL=https://api.staging.guaracloud.com
guara whoami

# Via flag
guara whoami --api-url https://api.staging.guaracloud.com

# Via config (persisted)
guara config set apiUrl https://api.staging.guaracloud.com

Verifying authentication

Check who you are logged in as:

guara whoami

✓ Authenticated as [email protected]

  Account
  Name        Your Name
  Email       [email protected]
  Tier        pro
  Role        owner
  Founder     No
  ID          abc123...

Logging out

Remove stored credentials:

guara logout

This removes the API key from the system keychain and any local config file.

Credential storage

The CLI stores credentials using this priority:

1. System keychain (preferred) — macOS Keychain, Windows Credential Manager, or Linux Secret Service via the keytar library
2. Config file (fallback) — ~/.config/guara/config.json with restricted file permissions

The keychain is always tried first. The config file is used only when the keychain is unavailable (for example, in a headless server without a display server).

Authentication priority

When resolving the API key, the CLI checks these sources in order:

1. --api-key flag on the command line
2. GUARA_API_KEY environment variable
3. System keychain
4. Config file (~/.config/guara/config.json)

The first key found is used. If no key is found, commands that require authentication will prompt you to log in (or fail in non-interactive mode).