CLI Key Rotation & Multi-Account

Overview

The CLI & API Key Auth page covers the basics of authenticating the CLI — environment variables, command flags, and a config file. This page picks up from there and focuses specifically on day-to-day key lifecycle management: checking your auth status, rotating tokens, working across multiple accounts with aliases, and wiring the CLI into a CI/CD pipeline safely.

To see which account is currently active, along with any other authenticated accounts and their organization/environment:

core-system auth status

To view your current token (masked by default, for safe display in a shared terminal):

core-system auth token

To reveal the full, unmasked token when you actually need to copy it:

core-system auth token --show

For a fuller account summary — user ID, email, organization details, and permissions — use:

core-system auth whoami

The CLI supports two distinct authentication approaches, and it's worth choosing deliberately rather than defaulting to whichever you used first:

• OAuth login — opens a browser for interactive sign-in, with automatic token refresh handled for you. This is the recommended flow for day-to-day interactive CLI use.
• Direct API key — supplied via environment variable (CORE_SYSTEM_API_KEY), the --api-key flag, or a config file (~/.core-system-cli.yaml). This is the recommended flow for automation, since there's no browser step and no user-specific session involved.

# OAuth login (interactive)
core-system login

# API key via environment variable
export CORE_SYSTEM_API_KEY=your-api-key
core-system assistant list

# API key via command flag
core-system assistant list --api-key your-api-key

# API key via config file
# ~/.core-system-cli.yaml
api_key: your-api-key
base_url: https://api.sulus.ai  # Optional custom endpoint

Credentials from either flow are stored using your platform's native credential manager — Keychain on macOS, Secret Service API / keyring on Linux, and Credential Manager on Windows.

Refresh the token for your current active account:

core-system auth refresh

Refresh tokens across every authenticated account at once:

core-system auth refresh --all

Rotate credentials regularly as a security practice — you can update an API key in the dashboard without changing anything in your CLI or server configuration, since the CLI simply re-authenticates against whatever key is currently valid.

If you work across more than one Sulus account or environment (for example, production and staging), add each as a separate authenticated account rather than repeatedly logging in and out:

# Add an additional account without logging out of the current one
core-system auth login

# Assign a memorable alias at login
core-system auth login --alias production

# Update the alias for an already-authenticated account
core-system auth alias [email protected] production

Switch between accounts using the alias, an email, or an interactive menu:

# Switch by alias
core-system auth switch staging

# Switch by email
core-system auth switch [email protected]

# Interactive selection menu
core-system auth switch

core-system auth status is the fastest way to confirm which alias is currently active before running a command that affects live resources.

For automated pipelines, use an API key stored as a secret and referenced via environment variable — never an interactive OAuth login, which requires a browser:

# GitHub Actions example
env:
  CORE_SYSTEM_API_KEY: ${{ secrets.SULUS_PROD_KEY }}

steps:
  - name: Deploy Assistant
    run: |
      core-system assistant create --file assistant.json

To remove an account from the CLI's stored credentials:

# Log out of the current account
core-system auth logout

# Log out of a specific account
core-system auth logout [email protected]

# Log out of every authenticated account
core-system auth logout --all

Security Best Practices

• Use OAuth login for interactive, human use; reserve API keys for automation
• Never commit API keys to version control
• Use descriptive aliases and credential names (e.g. "production", "staging") so it's obvious which account is active
• Rotate API keys regularly, and immediately if you suspect a key has been exposed
• Run core-system auth logout --all on shared or temporary machines when you're done

For the underlying environment variable, flag, and config-file authentication methods this page builds on, see the CLI & API Key Auth page.