CLI Setup

Overview

The Polystack command-line interface gives you full control over every platform service directly from your terminal. With a single authenticated session you can provision instances, manage volumes, configure networks, and automate infrastructure workflows — without opening a browser. The CLI is compatible with all major operating systems and integrates cleanly into CI/CD pipelines and shell scripts.

Prerequisites

An active Polystack account with project access
Python 3.8 or later installed on your workstation
Network access to your OpenStack API endpoint

Installation

Install the Polystack CLI using the package manager for your operating system.

Ubuntu / Debian
CentOS / RHEL
macOS
pip (any OS)

Install on Ubuntu / Debian

sudo apt update
sudo apt install -y python3-pip python3-venv
pip3 install python-openstackclient

Install into a virtual environment to avoid conflicts with system Python packages: python3 -m venv ~/.polystack-cli && source ~/.polystack-cli/bin/activate && pip install python-openstackclient

Install on CentOS / RHEL

sudo dnf install -y python3-pip
pip3 install --user python-openstackclient

Add the user bin directory to your PATH if it is not already present:

Update PATH

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Install on macOS (Homebrew)

brew install python@3
pip3 install python-openstackclient

Alternatively, use pipx for an isolated installation:

Install with pipx

brew install pipx
pipx install python-openstackclient

Install via pip

pip install python-openstackclient

Python 3.8 or later is required. Verify with python3 --version before installing.

Confirm the installation completed successfully:

Verify installation

openstack --version

The command prints the installed version, e.g., openstack 6.x.x.

Authentication

The CLI authenticates using an RC (credentials) file that sets environment variables for your session. Your administrator provides this file, or you can create it manually.

Obtain your RC file

Your administrator provides the RC (credentials) file for your project. This file contains the authentication endpoint, project name, and your username.Alternatively, create the file manually with the following content:

openrc.sh

export OS_AUTH_URL=https://api.<your-domain>:5000/v3
export OS_PROJECT_NAME=<your-project>
export OS_PROJECT_DOMAIN_NAME=Default
export OS_USERNAME=<your-username>
export OS_USER_DOMAIN_NAME=Default
export OS_REGION_NAME=RegionOne
export OS_IDENTITY_API_VERSION=3
echo "Please enter your Polystack password for project $OS_PROJECT_NAME as user $OS_USERNAME:"
read -sr OS_PASSWORD_INPUT
export OS_PASSWORD=$OS_PASSWORD_INPUT

Each project has its own RC file. Ask your administrator for the correct OS_AUTH_URL and OS_PROJECT_NAME values for your environment.

Source the credentials file

Open a terminal and source the file to load your credentials into the current shell session:

Load credentials

source openrc.sh

Enter your Polystack account password when prompted.

Verify authentication

Confirm the CLI can authenticate successfully:

Verify token

openstack token issue

A valid response displays a token ID, expiry, and your project details.

Authentication is working. Your session is valid for 1 hour by default.

The RC file exports the following environment variables to configure the CLI client. You can also set these manually or store them in a clouds.yaml file for multi-cloud management.

Variable	Purpose
`OS_AUTH_URL`	Polystack Identity service endpoint
`OS_PROJECT_NAME`	Target project for all operations
`OS_PROJECT_DOMAIN_NAME`	Project domain (typically `Default`)
`OS_USERNAME`	Your Polystack account username
`OS_USER_DOMAIN_NAME`	User domain (typically `Default`)
`OS_REGION_NAME`	Target region for API calls
`OS_IDENTITY_API_VERSION`	Identity API version (`3`)

Command Structure

Every CLI command follows the same pattern: resource type, action, and optional flags.

openstack <resource> <action> [options] [arguments]

# Pattern: openstack <resource> list [--filter value]
openstack server list --status ACTIVE
openstack volume list --status available
openstack network list --internal

# Pattern: openstack <resource> create --option value <name>
openstack server create \
  --flavor m1.medium \
  --image ubuntu-24.04 \
  --network private \
  --key-name my-keypair \
  web-server-01

# Pattern: openstack <resource> show <name-or-id>
openstack server show web-server-01
openstack server show --format json web-server-01

# Pattern: openstack <resource> delete <name-or-id>
openstack server delete web-server-01

Most commands accept either the resource name or UUID as the final argument. Use UUIDs in scripts to avoid ambiguity when multiple resources share the same name.

Output Formats

The CLI supports multiple output formats controlled by the --format flag.

Flag	Output Type	Best Used For
`--format table`	Human-readable table (default)	Interactive use, quick inspection
`--format json`	JSON object or array	Scripts, parsing, API-like output
`--format yaml`	YAML document	Configuration files, readable serialization
`--format csv`	Comma-separated values	Spreadsheet import, bulk reporting
`--format value`	Plain values, one per line	Shell variable assignment, `grep` pipelines

openstack server show my-vm --format json

# Use --format value with -c to extract one column
openstack server show my-vm --format value -c status

openstack server list --format csv --quote all

Tips and Tricks

Set up shell aliases for common commands

Add aliases to your shell profile (~/.bashrc or ~/.zshrc) to speed up repetitive tasks:

Recommended aliases (~/.bashrc)

alias osl='openstack server list'
alias ovl='openstack volume list'
alias onl='openstack network list'
alias oil='openstack image list'
alias oss='openstack server show'
alias osrc='source ~/openrc.sh'

Reload your shell after adding aliases:

Reload shell config

source ~/.bashrc

Enable bash completion

The CLI ships with a completion script that enables tab-completion for commands, resource names, and flags.

Enable bash completion

# Add to ~/.bashrc
eval "$(openstack complete)"

Enable zsh completion

# Add to ~/.zshrc
eval "$(openstack complete)"

After reloading your shell, press Tab after any partial command to see available completions.

Enable debug mode for troubleshooting

Pass --debug to any command to print the full HTTP request and response, including headers and token details. This is useful for diagnosing authentication errors or unexpected API responses.

Debug a failing command

openstack server list --debug 2>&1 | less

Debug output includes your authentication token. Avoid sharing or storing this output in logs or tickets.

Manage multiple clouds with clouds.yaml

Instead of sourcing separate RC files, define all your environments in a single clouds.yaml file stored at ~/.config/openstack/clouds.yaml:

~/.config/openstack/clouds.yaml

clouds:
  polystack-prod:
    auth:
      auth_url: https://api.<your-domain>:5000/v3
      project_name: production
      username: your-username
      password: your-password
      user_domain_name: Default
      project_domain_name: Default
    region_name: RegionOne
    identity_api_version: 3
  polystack-dev:
    auth:
      auth_url: https://api-dev.<your-domain>:5000/v3
      project_name: development
      username: your-username
      password: your-password
      user_domain_name: Default
      project_domain_name: Default
    region_name: RegionOne
    identity_api_version: 3

Switch between environments using --os-cloud:

Use a named cloud profile

openstack --os-cloud polystack-prod server list
openstack --os-cloud polystack-dev server list

Set OS_CLOUD=polystack-prod in your shell to make a profile the default for all commands in that session.

Service CLI References

Each service has a dedicated CLI reference with complete command syntax, options, and examples.

Compute CLI

Instances, flavors, keypairs, server groups, console, and live migration commands.

Block Storage CLI

Volumes, snapshots, backups, volume types, and cross-project transfers.

Networking CLI

Networks, subnets, routers, floating IPs, security groups, and ports.

Images CLI

Upload, download, share, and manage virtual machine images.

Orchestration CLI

Heat stacks, resources, events, outputs, and template validation.

Identity CLI

Projects, users, roles, groups, and application credentials.

Load Balancer CLI

Load balancers, listeners, pools, members, and health monitors.

DNS CLI

Zones, record sets, PTR records, and zone transfers.

Key Manager CLI

Secrets, containers, orders, and access control lists.

Object Storage CLI

Containers, objects, large object uploads, and temporary URLs.

Kubernetes CLI

Cluster templates, clusters, and node group management.

Core Services

Other Services

Overview

Installation

Authentication

Obtain your RC file

Source the credentials file

Verify authentication

Command Structure

Output Formats

Tips and Tricks

Service CLI References

Compute CLI

Block Storage CLI

Networking CLI

Images CLI

Orchestration CLI

Identity CLI

Load Balancer CLI

DNS CLI

Key Manager CLI

Object Storage CLI

Kubernetes CLI

​Overview

​Installation

​Authentication

Obtain your RC file

Source the credentials file

Verify authentication

​Command Structure

​Output Formats

​Tips and Tricks

​Service CLI References

Compute CLI

Block Storage CLI

Networking CLI

Images CLI

Orchestration CLI

Identity CLI

Load Balancer CLI

DNS CLI

Key Manager CLI

Object Storage CLI

Kubernetes CLI

Overview

Installation

Authentication

Command Structure

Output Formats

Tips and Tricks

Service CLI References