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
  • Team management — customers, projects, users, roles, invitations, organization groups, permission reviews
  • Marketplace — browse offerings, and provision/terminate OpenStack tenants, instances, and volumes through Waldur's order flow

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.

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, JMESPath, and streaming large lists with --format ndjson
  3. Managing resources — create/update/delete, request-body skeletons, and per-resource action verbs (start/stop/detach/approve/...)
  4. Provisioning — the marketplace order flow (provision/terminate), for OpenStack and any other offering type, plus the generic wait verb every resource gets
  5. Recipes & tips — real-world workflows and things worth knowing
  6. Troubleshooting — errors, --debug, exit codes, and shell completions

Development

src/commands/, src/cli.rs, and src/schema.rs are generated from Waldur's OpenAPI schema by waldur-cli-generator — don't edit them by hand; see that repo for how to regenerate. The rest of src/ (lib.rs, main.rs, config.rs, output.rs, pagination.rs, http.rs, request.rs, filter.rs, query.rs, order.rs, progress.rs) is hand-written and permanent.

The crate is split into a library (everything except the Cli/main() entry point in main.rs) and a thin binary, so tests/ can exercise the actual logic directly:

1
2
cargo test --locked
cargo clippy --all-targets

Networked code (pagination, http, order) is tested against an in-process HTTP mock (wiremock) rather than a live Waldur instance — see tests/*.rs for examples. CI runs both cargo test and cargo clippy on every merge request.

License

MIT.