CLI Reference

The quazzar-cli tool lets you manage your Cloud OS server from the terminal. It is a separate binary from the main quazzar server and communicates with the Cloud OS REST API.

Installation

APT (when available)

sudo apt install quazzar-cli

Build from Source

git clone https://github.com/quazzar/cloud-os.git
cd cloud-os
make build-cli

The compiled binary is placed in ./bin/quazzar-cli.

Authentication

Before using the CLI, authenticate with your Cloud OS instance:

quazzar-cli login --server https://your-server.example.com

You will be prompted for your email and password. If 2FA is enabled, you will also be prompted for your TOTP code.

The authentication token is stored in ~/.quazzar/credentials.

Commands

System

Components

See Components.

Installer language. The installer and quazzar setup show English, Russian, Spanish or French, chosen from LC_ALL, then LC_MESSAGES, then LANG (anything else is English). For example LANG=fr_FR.UTF-8 sudo -E quazzar setup. See Languages.

Apps

Backups

Updates

Cluster

See Clustering.

Control Center

After quazzar enroll the node appears in the Control Center fleet within a few seconds. See Onboarding.

Configuration

Authentication

Local administration (recovery)

These commands run on the server itself and only work under sudo (as root). They don’t use the REST API or a login: they talk to the running Quazzar service over a local admin socket (/var/lib/quazzar/run/admin.sock — <data dir>/run/admin.sock) that never listens on the network. The service checks who is connecting and accepts root only — not even the quazzar service account can reset a password — and the CLI refuses to start without root.

admin reset-password flags:

admin flags:

$ sudo quazzar-cli admin reset-password
Email: [email protected]
New password: ********
Confirm password: ********
✓ Password for [email protected] (admin) reset; 3 sessions signed out.

The new password is typed twice and hidden; it must be at least 8 characters. There is deliberately no password flag, so it never ends up in your shell history. For scripts, pipe the answers on stdin instead — one line each (email first when --email isn’t given):

printf '%s\n%s\n' "$NEW_PW" "$NEW_PW" | sudo quazzar-cli admin reset-password --email [email protected]

With --json, both commands print the result as JSON and the prompts go to stderr. The exit code is non-zero on any failure. Every reset is recorded in the activity log (auth.password_reset) and on the system timeline.

If the command says the service isn’t running, start it (sudo systemctl start quazzar) — the socket only exists while the service runs, and older Cloud OS versions don’t have it (update the server so it matches the CLI). “Must be run as root”, “permission denied” or “closed the connection” means you forgot sudo.

Docker: run the CLI inside the Cloud OS container (it runs as root there, and the CLI is included in the image):

docker exec -it <container> quazzar-cli admin reset-password

Kubernetes: The Helm chart runs the pod as a non-root user (uid 65534), so kubectl exec … quazzar-cli admin reset-password is refused by the root-only check. If you sign in through SSO, restore access in your identity provider. Otherwise run the pod as root for the reset (podSecurityContext.runAsUser: 0 in the chart values), run kubectl exec -it <pod> -- quazzar-cli admin reset-password, and then revert the setting.

cp-trust runs through the privileged helper. To list the operations the quazzar service account may run as root, use sudo quazzar-setup priv list.

Object storage

Runs on the server, as root, over the same local admin socket as admin (see above).

The command is refused until the move has finished (objstore_minio_purge_unavailable), for 6 minutes after the switch, and whenever the Settings → Components Delete button would be refused — for example when Garage cannot be shown to hold everything that was moved, or MinIO files changed after the switch (see Deleting the old MinIO data). Progress is in Settings → Components. With --json it prints {"freed_bytes": N, "binary_removal_started": true}.

Global Flags

Output Formats

By default, the CLI outputs human-readable colored tables. Use --json for machine-parseable output:

# Human-readable
quazzar-cli status
 
# JSON
quazzar-cli status --json

Example Output

$ quazzar-cli status
Quazzar Cloud OS v0.2.9
-------------------------
  CPU:    23.4%
  RAM:    3.2 / 8.0 GB (40%)
  Disk:   45.1 / 100.0 GB (45%)
  Apps:   12 running, 2 stopped
  Uptime: 14d 6h 32m

Shell Completions

Enable tab completion for your shell:

# Bash — add to ~/.bashrc
eval "$(quazzar-cli completion bash)"
 
# Zsh — add to ~/.zshrc
eval "$(quazzar-cli completion zsh)"
 
# Fish — add to ~/.config/fish/config.fish
quazzar-cli completion fish | source

Usage Examples

# Install an app and check its status
quazzar-cli apps install nextcloud
quazzar-cli apps list
 
# Create a backup
quazzar-cli backup create
quazzar-cli backup list
 
# Check for updates
quazzar-cli update check
 
# Tail app logs
quazzar-cli apps logs nextcloud --follow
 
# Scripting: restart all stopped apps
quazzar-cli apps list --json | \
  jq -r '.[] | select(.status == "stopped") | .id' | \
  xargs -I {} quazzar-cli apps start {}