Skip to content

Getting started

Command structure

Every command has the same three-level shape:

1
waldur-cli <group> <resource> <verb> [arguments] [options]
  • group — a broad area: openstack, team, or marketplace
  • resource — what you're acting on: instance, customer, offering, …
  • verb — what to do: list, get, create, update, delete, provision, terminate
1
2
3
waldur-cli team customer list
waldur-cli openstack instance get <uuid>
waldur-cli openstack tenant provision --request-file vpc.yaml

--help works at every level and is the authoritative reference for what a specific command accepts — including the exact filter keys and request fields each resource supports:

1
2
3
4
waldur-cli --help                        # top-level groups
waldur-cli team --help                   # resources in the team group
waldur-cli team customer --help          # verbs for customers
waldur-cli team customer list --help     # every flag, with the valid --filter/--fields keys

Authentication

The CLI needs two things: an API URL and an access token. There are three ways to provide them, checked in this order (first match wins):

  1. --api-url / --token flags on the command
  2. WALDUR_API_URL / WALDUR_ACCESS_TOKEN environment variables
  3. Saved credentials from waldur-cli login

Environment variables

Best for CI, containers, and scripts:

1
2
3
4
export WALDUR_API_URL=https://waldur.example.com
export WALDUR_ACCESS_TOKEN=your-token

waldur-cli team customer list

Persisted login

Best for interactive/local use — login verifies the URL + token against GET /api/users/me/ and saves them, so you don't re-enter them every time:

1
2
3
4
5
waldur-cli login --api-url https://waldur.example.com --token your-token
# omit either flag to be prompted for it (the token prompt is masked)

waldur-cli team customer list   # uses the saved credentials
waldur-cli logout               # removes them

The credentials file lives in your platform config directory (e.g. ~/.config/waldur-cli/credentials.toml on Linux) with owner-only permissions (0600 on Unix).

whoami

whoami shows who the currently-resolved credentials belong to — whichever source they came from — without changing anything. Run it before a destructive command to confirm you're pointed at the right instance and identity:

1
waldur-cli whoami

Multiple deployments (--profile)

If you work with more than one Waldur instance (prod/staging, or several customer deployments), named profiles let you keep separate saved credentials and switch between them with --profile or the WALDUR_PROFILE environment variable:

1
2
3
4
5
6
7
waldur-cli login --profile prod    --api-url https://waldur.example.com     --token ...
waldur-cli login --profile staging --api-url https://staging.example.com    --token ...

waldur-cli team customer list --profile staging
WALDUR_PROFILE=prod waldur-cli team customer list

waldur-cli logout --profile staging   # removes only that profile

Omitting --profile/WALDUR_PROFILE uses the profile named default. Each profile is a [profiles.NAME] table in the same credentials.toml.

Tip

Set WALDUR_PROFILE in a terminal's shell rc (or per-tab) to pin an environment for a whole session, so you can't accidentally run a command against the wrong instance.

Working in a project

Most of Waldur is organized under projects — nearly every OpenStack resource, and provisioning, is project-scoped. Rather than pass --filter project_uuid=<uuid> on every list and paste a project URL into every order, you can set an ambient current project (a project's UUID, like a kubectl namespace or gcloud config set project). It's resolved, first match wins, from:

  1. the --project <uuid> flag
  2. the WALDUR_PROJECT environment variable
  3. the profile's saved default (set-project)

Save a per-profile default once and forget it:

1
2
3
4
5
6
7
waldur-cli team project list --filter name_exact="My Project"   # find the UUID
waldur-cli set-project <uuid>                                    # save it on the active profile

waldur-cli openstack instance list          # automatically scoped to that project
waldur-cli openstack tenant provision --request-file vpc.yaml    # project filled in for you

waldur-cli unset-project                     # clear it

When a project scope is active, it's applied only where it's meaningful — as a project_uuid filter on resources whose list supports it, and as the project on provision orders. Resources that aren't project-scoped (like team customer or team role) ignore it. An explicit value always wins: --filter project_uuid=<other> on a list, or a project field in a provision/order body, overrides the ambient scope.

Note

--profile and --project are different axes: --profile selects which deployment + token; --project selects which project within it. whoami prints the active project scope (to stderr, so it never pollutes --format json output) — a cheap way to confirm it before a scoped command.

Output formats

--format controls how results are rendered. It's available on every command; the default is table.

Format Best for Notes
table reading at a terminal (default) curated columns per resource
json scripts, jq, agents pretty-printed, the complete object
tsv shell loops, cut/awk tab-separated, one row per line, no header, curated columns
toon feeding results to an LLM lossless like json, far fewer tokens
ndjson large lists, streaming pipes one compact object per line, printed as pages arrive 
1
2
3
4
5
waldur-cli team customer list                    # table
waldur-cli team customer list --format json      # complete objects, pretty JSON
waldur-cli team customer list --format tsv        # tab-separated rows
waldur-cli team customer list --format toon       # token-efficient, for LLM context
waldur-cli team customer list --format ndjson     # streamed, one object per line

table and tsv show each resource's curated columns (a useful default subset). json and toon serialize the complete object. See Querying resources for narrowing what's fetched with --fields, and Recipes & tips for when each format earns its keep.

TOON, for LLMs

--format toon emits TOON (Token-Oriented Object Notation) — the same information as JSON, but for a uniform array of objects (what every list returns) the field names are declared once in a header instead of repeated on every row, which cuts token usage substantially when piping results into an LLM's context:

1
2
3
4
5
waldur-cli team customer list --format toon
# [3]{blocked,name,uuid}:
#   false,Acme Corp,"11111111-1111-1111-1111-111111111111"
#   true,Beta LLC,"22222222-2222-2222-2222-222222222222"
#   false,Gamma Inc,"33333333-3333-3333-3333-333333333333"

NDJSON, for large or streamed lists

--format ndjson prints one compact JSON object per line instead of one pretty-printed array — and, for list, prints each page as it arrives rather than fetching the complete result set first. See Querying resources for the streaming details and its one caveat (--jmespath).