Configuration

hudl reads configuration from multiple sources, applied in order of precedence:

Command-line flags — highest priority, override everything.
Environment variables — HUDL_API_KEY, HUDL_WORKSPACE, HUDL_REGION, HUDL_OUTPUT.
./hudl.toml — project-local config, checked into your repo.
~/.hudl/config.toml — user-global config, created by hudl login.
Built-in defaults — lowest priority.

Project config

A hudl.toml in your repository root lets your whole team share the same workspace and region context:

workspace = "acme-prod"
region    = "eu2"
output    = "table"

[defaults.vm]
image_id       = "ubuntu-24.04"
flavor_id      = "c2.small"
boot_disk_size = 50

With this file, hudl vm create web-01 --key laptop --sg default automatically uses the image, flavor, and disk size from your project config.

Keep secrets out of project config

Never put api_key in hudl.toml. Keep it in ~/.hudl/config.toml or the HUDL_API_KEY environment variable.

User config

The user config lives at ~/.hudl/config.toml and is created by hudl login. It stores your API key and default context:

api_key   = "mk_xxx"
workspace = "acme-staging"
region    = "us1"
output    = "table"

Environment variables

Variable	Description
`HUDL_API_KEY`	API key for authentication.
`HUDL_WORKSPACE`	Default workspace slug.
`HUDL_REGION`	Default region code.
`HUDL_OUTPUT`	Default output format (`table`, `json`, `yaml`, `wide`, `name`).

Environment variables override both project and user config files, but are overridden by command-line flags.

Output formats

Every command supports --output (-o):

Format	Use case
`table`	Default on a TTY — human-friendly columns.
`json`	Machine-readable; pipe to `jq`.
`yaml`	GitOps-friendly; good for storing state.
`wide`	Same as `table` with every column visible.
`name`	Just IDs, one per line — pipe to `xargs` or shell loops.

Examples

# human-readable table (default)
hudl vm list

# JSON for scripting
hudl vm get abc123 -o json | jq '.status'

# just names for piping
hudl vm list -o name | xargs -I{} hudl vm status {}

# YAML for config-as-code workflows
hudl sg get web-tier -o yaml > sg-web-tier.yaml

Idempotency

Every mutating command (create, delete, action, etc.) carries an automatic idempotency key, so retries are always safe. You can also pin one explicitly:

hudl vm create web-01 --image ubuntu-24.04 --flavor c2.small \
  --boot-disk-size 50 --idempotency-key "deploy-$(git rev-parse --short HEAD)"

This is useful in CI pipelines where a job might be retried — the same idempotency key ensures the VM is only created once.

Shell completion

hudl generates completions for every major shell. Tab-complete resource names, region codes, image slugs, and even live VM IDs.

# zsh
hudl completion zsh > "${fpath[1]}/_hudl"

# bash
hudl completion bash > /etc/bash_completion.d/hudl

# fish
hudl completion fish > ~/.config/fish/completions/hudl.fish

After installing completions, restart your shell or run source ~/.zshrc (or equivalent).