Skip to main content

CLI Multi-Context Authentication

The UnderControl CLI supports managing multiple accounts and API endpoints using a kubectl-style context system. This allows you to easily switch between different servers, accounts, or environments.

Overview​

A context is a named configuration that contains:

  • API URL (server endpoint)
  • Authentication token or API key
  • Username (for display)

You can have multiple contexts (e.g., personal, work, staging) and switch between them instantly.

Configuration File​

Contexts are stored in ~/.config/ud/config.yaml:

current-context: personal
contexts:
- name: personal
  context:
    api_url: https://api.undercontrol.app
    token: eyJhbGciOi...
    user: john@example.com
- name: work
  context:
    api_url: https://ud.company.com
    token: eyJhbGciOi...
    user: john@company.com
- name: staging
  context:
    api_url: http://localhost:4000
    api_key: ak_test_xxx

Commands​

List All Contexts​

ud config get-contexts

Output:

CURRENT  NAME      API URL                      USER
*        personal  https://api.undercontrol.app john@example.com
         work      https://ud.company.com       john@company.com
         staging   http://localhost:4000        (api-key)

The * indicates the currently active context.

Switch Context​

ud config use-context work

Output:

Switched to context "work".

Show Current Context​

ud config current-context

Output:

work

Create or Update Context​

# Create a new context
ud config set-context staging --api-url http://localhost:4000

# Create with API key (for CI/CD)
ud config set-context ci --api-url https://api.example.com --api-key ak_xxx

# Update existing context
ud config set-context work --api-url https://new-api.company.com

Delete Context​

ud config delete-context staging

Rename Context​

ud config rename-context work production

View Full Configuration​

ud config view

Output (tokens are partially masked):

current-context: personal
contexts:
- name: personal
  context:
    api_url: https://api.undercontrol.app
    user: john@example.com
    token: eyJhbGciOi...xyz
- name: work
  context:
    api_url: https://ud.company.com
    user: john@company.com
    token: eyJhbGciOi...abc

Login with Context​

When logging in, you can specify which context to save credentials to:

# Login and save to a new context
ud login --context work --api-url https://ud.company.com

# Login to existing context (updates credentials)
ud login --context personal

Ad-hoc Context with --context Flag​

The --context global flag lets you run any command against a different context without switching:

# List tasks from work context (without changing default)
ud --context work get task

# View a task in staging
ud --context staging describe task abc123

# Create a task in a different account
ud --context personal task create "Buy groceries"

# Launch TUI with a specific context
ud --context work

This is a temporary override — it does not modify your current-context in the config file. Your default context remains unchanged after the command completes.

tip

The --context flag is the recommended way to run one-off commands against a different context. Use ud config use-context only when you want to permanently switch.

Priority Order​

When determining which context to use, the CLI checks in this order (highest priority first):

  1. --context flag
  2. UD_CONTEXT environment variable
  3. current-context in config file

Environment Variable Overrides​

You can also override context settings using environment variables:

VariableDescription
UD_CONTEXTOverride current context
UD_API_URLOverride API URL
UD_API_KEYOverride API key
UD_TOKENOverride auth token

Example:

# Use different context for one command
UD_CONTEXT=staging ud task list

# Override API URL temporarily
UD_API_URL=http://localhost:4000 ud task list

Common Workflows​

Personal + Work Setup​

# Setup personal account
ud login --context personal --api-url https://api.undercontrol.app

# Setup work account
ud login --context work --api-url https://ud.company.com

# Use --context flag for one-off commands (recommended)
ud --context personal get task  # Lists personal tasks
ud --context work get task      # Lists work tasks

# Or switch default context permanently
ud config use-context personal
ud get task  # Lists personal tasks

Development + Production​

# Local development
ud config set-context dev --api-url http://localhost:4000
ud login --context dev

# Production
ud login --context prod --api-url https://api.undercontrol.app

# Quick switching
ud config use-context dev
ud config use-context prod

CI/CD with API Key​

# Create context with API key (no interactive login needed)
ud config set-context ci \
  --api-url https://api.undercontrol.app \
  --api-key ak_your_api_key

# Use in CI/CD scripts
ud config use-context ci
ud task create "Deployment completed" -d "Version 1.2.3"

Or use environment variables:

export UD_API_URL=https://api.undercontrol.app
export UD_API_KEY=ak_your_api_key
ud task list

Migration from Single Context​

If you have an existing config file with the old single-context format:

# Old format
api_url: https://api.undercontrol.app
token: eyJhbGciOi...

The CLI automatically migrates it to the new format:

# New format (auto-migrated)
current-context: default
contexts:
- name: default
  context:
    api_url: https://api.undercontrol.app
    token: eyJhbGciOi...

No manual action required - the migration happens automatically on first use.

Troubleshooting​

Context Not Found​

Error: context "work" not found

Solution: Create the context first with ud config set-context work --api-url <url> or ud login --context work.

Not Logged In​

Error: not logged in. Run 'ud login' first or set UD_API_KEY environment variable

Solution: The current context has no authentication. Run ud login or set UD_API_KEY.

Wrong Context​

If commands are hitting the wrong server, check your current context:

ud config current-context
ud config get-contexts

Switch to the correct context with ud config use-context <name>.