Skip to content

Use the OpenStack CLI

Install the OpenStack client locally, authenticate with an application credential, and drive Breqwatr Cloud from the command line — for scripts, CI runs, or anything the Portal doesn't surface.

Prerequisites

  • An application credential for the project you want to work in. The credential page generates a ready-to-use clouds.yaml (and an openrc.sh alternative) — download whichever fits your tooling. Application credentials are scoped to one project; if you need to drive a different project, mint a separate credential.
  • Python 3.x on your local machine.

Steps

1. Install the CLI

macOS / Linux

python3 -m venv ~/.openstack-venv
source ~/.openstack-venv/bin/activate
pip install --upgrade pip
pip install python-openstackclient

Windows (PowerShell)

Install Python 3 from python.org with "Add Python to PATH" ticked, then:

python -m venv $HOME\openstack-venv
$HOME\openstack-venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install python-openstackclient

2. Load your credentials

clouds.yaml lets you keep credentials for multiple projects in one file and refer to them by name.

mkdir -p ~/.config/openstack
mv ~/Downloads/clouds.yaml ~/.config/openstack/clouds.yaml
chmod 600 ~/.config/openstack/clouds.yaml

On Windows the equivalent path is %APPDATA%\openstack\clouds.yaml.

Every subsequent CLI call selects the cloud by name:

openstack --os-cloud breqwatr server list

If you already have a clouds.yaml with other clouds in it, paste the new entry (the inner key under clouds:) into the existing file rather than overwriting.

Option B — openrc.sh (shell variables)

The openrc.sh form exports OS_* variables into your shell. Use this when a tool can't read clouds.yaml or you want a single project's credentials always active.

macOS / Linux
chmod 600 ~/Downloads/openrc.sh
source ~/Downloads/openrc.sh

The variables are scoped to the current shell session; source it again in new sessions or add it to your shell profile.

Windows (PowerShell)

PowerShell can't source .sh files directly. The simplest path is to install Git for Windows and import the variables once:

bash -c "source ~/Downloads/openrc.sh && env" | ForEach-Object {
    if ($_ -match '^(OS_).*') {
        $name, $value = $_.Split('=', 2)
        setx $name $value | Out-Null
    }
}

Open a new PowerShell window to pick up the variables. As an alternative, run the CLI from WSL where the standard source ~/openrc.sh works.

3. Verify the connection

openstack --os-cloud breqwatr server list

You should see the instances in the project (or an empty list if there aren't any yet). If you get an authentication error, confirm the credential hasn't been revoked from the Portal's Application credentials page.

4. Look up what to pass to commands

The Portal shows you names; the CLI usually wants IDs or names too. Useful lookups:

openstack --os-cloud breqwatr image list
openstack --os-cloud breqwatr flavor list
openstack --os-cloud breqwatr network list
openstack --os-cloud breqwatr keypair list
openstack --os-cloud breqwatr security group list

5. Launch an instance from the CLI

openstack --os-cloud breqwatr server create \
  --image "Ubuntu 24.04" \
  --flavor m1.small \
  --network default \
  --key-name laptop-mike \
  --security-group default \
  --security-group web-servers \
  my-web-01

Add --user-data ./cloud-init.yaml to pass a cloud-init script (same shape as the User data textarea on the Portal launch form).

The instance shows up on the Portal's Instances page within a few seconds, just as if you'd used the Portal directly.

Verification

openstack --os-cloud breqwatr server show my-web-01
openstack --os-cloud breqwatr server list

my-web-01 should appear with status ACTIVE.

Next steps