Authentication

hudl uses API keys for authentication. Store a key once and the CLI reuses it from ~/.hudl/config.toml, or inject it per-command via environment variables.

Getting an API key

Generate an API key from the Huddle Cloud dashboard under Settings > API Keys. API keys start with mk_ and grant the same permissions as your user account within a workspace.

Save an API key

hudl login --token mk_xxx

This writes the key to ~/.hudl/config.toml. The file is created with 0600 permissions so only your user can read it.

Or prompt for it interactively (the key is not echoed):

hudl login

Environment variable

For CI pipelines, containers, and scripting, set the key as an environment variable:

export HUDL_API_KEY=mk_xxx
hudl vm list   # uses the env var

The environment variable takes precedence over the stored config file. This is useful for running different workspaces in parallel:

HUDL_API_KEY=mk_prod hudl vm list --workspace acme-prod
HUDL_API_KEY=mk_staging hudl vm list --workspace acme-staging

Workspace and region context

Your default workspace and region are stored in the user config. Most commands require both to be set.

hudl ctx                    # show current workspace + region
hudl ctx use acme-staging   # switch workspace
hudl ctx region us1         # switch region

You can override either on a per-command basis without changing the stored context:

hudl vm list --workspace acme-prod --region eu2

Multiple workspaces

If you work across multiple workspaces, you can use a project-level hudl.toml to set the context per repository:

# ./hudl.toml (checked into your repo)
workspace = "acme-prod"
region    = "eu2"

See Configuration for the full precedence order.

CI/CD setup

For GitHub Actions or other CI systems, store your API key as a secret and export it:

# .github/workflows/deploy.yml
env:
  HUDL_API_KEY: ${{ secrets.HUDL_API_KEY }}

steps:
  - run: |
      curl -fsSL https://get.huddle01.com/hudl | sh
      hudl vm list --workspace acme-prod --region eu2 -o json

Inspect and clear auth

hudl auth status   # show the authenticated user and active workspace
hudl auth clear    # remove stored credentials from ~/.hudl/config.toml