Skip to content

waldur-cli

A scriptable, LLM/agent-friendly command-line tool for Waldur MasterMind. It wraps the Waldur REST API behind a small, consistent command tree and is built for two audiences equally: humans at a terminal, and scripts/agents consuming machine-readable output.

It covers a curated slice of the API:

  • OpenStack — tenants, instances, volumes, networks, subnets, security groups, floating IPs, plus the flavor/image catalog
  • Team management — customers, projects, users, roles
  • Marketplace — browse offerings, and provision/terminate OpenStack tenants, instances, and volumes through Waldur's order flow
  • Auth — manage your own personal access tokens and SSH keys

Every command follows the same shape — waldur-cli <group> <resource> <verb> — and the same verbs (list, get, create, update, delete, plus provision/terminate for marketplace resources) behave consistently across every resource. For anything outside that curated slice, waldur-cli api <METHOD> <PATH> calls any endpoint directly, using the same credentials and transport.

Installation

Pre-built binaries for Linux, macOS, and Windows are published to GitHub Releases on every version tag, via cargo-dist:

1
2
# Linux / macOS
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/waldur/waldur-cli/releases/latest/download/waldur-cli-installer.sh | sh

1
2
3
4
5
6
# Windows -- download first, then run as a local file. Piping the download
# straight into `iex` works too, but some AV/EDR products flag that
# fetch-and-execute-inline pattern on powershell.exe even though the script is
# harmless; running it as a file avoids that.
irm https://github.com/waldur/waldur-cli/releases/latest/download/waldur-cli-installer.ps1 -OutFile waldur-cli-installer.ps1
powershell -ExecutionPolicy Bypass -File waldur-cli-installer.ps1

Or build from source with a Rust toolchain: cargo build --release.

Updating

Once installed, you can update waldur-cli to the latest release directly from the terminal:

1
waldur-cli update

Quickstart

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

waldur-cli whoami                              # confirm who/where you're authenticated as
waldur-cli team customer list                  # a human-readable table
waldur-cli team project list --format json     # machine-readable, for scripts/agents
waldur-cli schema --compact                    # emit a JSON tool specification for LLM agents
waldur-cli openstack instance get 00000000000000000000000000000000

Every command and flag is documented in --help, at every level:

1
2
3
4
waldur-cli --help
waldur-cli openstack --help
waldur-cli openstack instance --help
waldur-cli openstack instance provision --help

Manual

The full guide lives in docs/:

  1. Getting started — authentication, profiles, command structure, and output formats
  2. Querying resources — list/get, filtering, field selection, server-side ordering, JMESPath, streaming large lists with --format ndjson, and opening a resource in the browser with get --web
  3. Managing resources — create/update/delete, request-body skeletons, per-resource action verbs (start/stop/detach/approve/...), and batching delete/action verbs over several UUIDs or a piped-in list --format ndjson
  4. Provisioning — the marketplace order flow (provision/terminate), for OpenStack and any other offering type, plus wait, for polling resources with real async server-side state to completion
  5. Recipes & tips — real-world workflows and things worth knowing
  6. Troubleshooting — errors, --debug, exit codes, and shell completions

Looking for a specific command? docs/reference/ has one page per waldur-cli <group> <resource> <verb>, each with its flags and a real example — generated from the same schema data the CLI itself is built from, so it never drifts from what's actually there.

Contributing to waldur-cli itself (not just using it)? See docs/development.md — the generator/target repo split, building and testing, regenerating the command surface, and cutting a release.

License

MIT.