PyxCloud CLI

The official command-line interface for the PyxCloud Platform.
Design, compare, deploy, and manage multi-cloud infrastructure — from your terminal or CI/CD pipeline.

Every command in the CLI maps 1:1 to the PyxCloud console sidebar — projects, architecture, key management, settings — so you can operate your entire cloud estate without a browser.

The CLI also ships a Local Shell Bridge (pyxcloud proxy) that lets the web console open real SSH sessions to your servers through a secure localhost WebSocket, bypassing browser security constraints entirely.

curl -sL https://github.com/PyxCloud/pyxcloud-cli/releases/latest/download/install.sh | bash

The script auto-detects your OS and architecture, installs the binary to /usr/local/bin, and configures shell autocompletion.

brew tap pyxcloud/tap
brew install pyxcloud

Download the .msi package from the Releases page to auto-configure the binary, update your PATH and register the pyxcloud:// Custom URI protocol automatically!

scoop bucket add pyxcloud https://github.com/PyxCloud/scoop-bucket.git
scoop install pyxcloud

Download the archive for your platform from the Releases page, extract it, and move the binary into your $PATH.

Every release publishes a checksums.txt signed alongside the binaries:

sha256sum -c checksums.txt

pyxcloud auth login

Opens your default browser for PKCE-secured SSO authentication via Keycloak. An offline token is stored locally so sessions persist across reboots.

# With an API token (created via `settings create-token`)
pyxcloud auth login --token pyxc_abc123...

# With a JWT access token
pyxcloud auth login --token eyJhbGciOi...

# With environment variable
export PYXCLOUD_TOKEN=pyxc_abc123...

pyxcloud auth login \
  --url https://api.pyxcloud.io \
  --auth-url https://auth.pyxcloud.io/realms/pyx \
  --client-id pyxcloud-cli

pyxcloud auth logout

Manage projects in the current organisation.

# List all projects (default action)
pyxcloud projects
pyxcloud projects list

# Create a new project
pyxcloud projects create --name "production-stack"
pyxcloud projects create --name "staging-env" --description "Staging environment"

# Delete a project and all its builds
pyxcloud projects delete --id 42
pyxcloud projects delete --id 42 --force

Full infrastructure lifecycle — build enumeration, cost comparison, deployment, status monitoring, and teardown.

pyxcloud arch builds -p 42

Retrieve the multi-cloud pricing comparison table — same data rendered in the console UI.

# Auto-detect architecture root nodes
pyxcloud arch compare -p 42 -v 0.1.0

# Filter to a specific resource table
pyxcloud arch compare -p 42 -v 0.1.0 --table load-balancer

# Interactive (prompts for provider credentials)
pyxcloud arch deploy -p 42 -v 0.1.0

# Non-interactive with inline credentials
pyxcloud arch deploy -p 42 -v 0.1.0 --non-interactive \
  --credentials '{"target":{"csp":"aws","account":"{...}"}}'

# Non-interactive with credentials file
pyxcloud arch deploy -p 42 -v 0.1.0 --non-interactive \
  --credentials-file creds.json

# Non-interactive using pre-bound accounts from the console
pyxcloud arch deploy -p 42 -v 0.1.0 --non-interactive

# Execute deployment script locally (streams tf apply directly to stdout)
pyxcloud arch deploy -p 42 -v 0.1.0 --local

pyxcloud arch status -p 42 -v 0.1.0

# With confirmation prompt
pyxcloud arch destroy -p 42

# Skip prompt (CI/CD)
pyxcloud arch destroy -p 42 --force

Manage cloud provider account bindings — the credentials PyxCloud uses to provision infrastructure.

# List all account bindings
pyxcloud accounts list

# Create with inline credentials
pyxcloud accounts create --provider aws --credentials '{"access_key_id":"...","secret_access_key":"..."}'

# Create with credentials from a file
pyxcloud accounts create --provider gcp --credentials-file sa-key.json --nickname "prod-gcp"

# Verify credentials are valid
pyxcloud accounts verify --id 42

# Delete an account binding
pyxcloud accounts delete --id 42
pyxcloud accounts delete --id 42 --force

Supported providers: aws, azure, gcp, digitalocean, linode, ubicloud, vultr, oracle, ibm, alibaba, stackit, ovh.

Import existing cloud infrastructure into PyxCloud — the CLI equivalent of the Import Wizard.

Scan a cloud account and list all discovered resources.

pyxcloud import discover --account 42

Output includes resource ID, type, name, region, and status — ready for selective import.

Create a new Build version from discovered resources.

# Import specific resources by ID
pyxcloud import build --account 42 --project 51 --select vm-abc123,vpc-def456

# Import all discovered resources
pyxcloud import build --account 42 --project 51 --all

Perform a zero-trust agentless scan for undocumented SSH keys residing in your compute instances over native SSH. The CLI connects via native OS shell and pushes discovered public payloads to the current web tracking UI.

pyxcloud import scan-vms --ips 192.168.1.1,192.168.1.2 --user ubuntu --token abc-123

Manage local secrets for local deployment (architecture deploy --local). These secrets are saved securely in ~/.pyxcloud/secrets.env and are strictly read by the local deployment worker without ever leaving your machine.

# Add a secret manually
pyxcloud secrets set AWS_ACCESS_KEY_ID=AKIA...

# List saved secrets (masked)
pyxcloud secrets list

# Delete a secret
pyxcloud secrets delete AWS_ACCESS_KEY_ID

# Interactively import all required secrets for a provider
pyxcloud secrets import --provider aws

Manage SSH key associations. Keys are split via Shamir Secret Sharing — one share stays in your database, the other in Vault. Recovery requires step-up re-authentication.

# List all keys
pyxcloud keystore list

# Create a new key pair
pyxcloud keystore create --label "prod-eu-west"

# Recover a private key (opens browser for re-auth)
pyxcloud keystore recover --id 5
pyxcloud keystore recover --id 5 --output my-key.pem

# Delete a key
pyxcloud keystore delete --id 5
pyxcloud keystore delete --id 5 --force

Organisation administration — identity, team, roles, seats, and API token lifecycle.

# Current identity
pyxcloud settings whoami

# Team management (admin)
pyxcloud settings team
pyxcloud settings seats
pyxcloud settings invite --email [email protected]

# Role management
pyxcloud settings assign-role --user-id <id> --role pyx-developer-role
pyxcloud settings remove-role --user-id <id> --role pyx-audit-role

# API tokens for CI/CD
pyxcloud settings tokens
pyxcloud settings create-token --name "github-actions"
pyxcloud settings revoke-token --id 42

Available roles: pyx-admin-role, pyx-developer-role, pyx-billing-manager-role, pyx-audit-role.

The proxy command starts a local WebSocket-to-SSH bridge on 127.0.0.1. The PyxCloud web console connects to this bridge to open real, interactive SSH sessions directly in the browser — no browser plugins, no proprietary agents.

Note for Windows Users: If using the recommended MSI Windows Installer, PyxCloud exposes a direct pyxcloud://proxy URI protocol natively into your operating system. Opening Shells from the Web dashboard spawns the bridge command in stealth background mode without opening stray console windows.

# Default port (13337)
pyxcloud proxy

# Custom port
pyxcloud proxy --port 9999

How it works:

1. The console frontend opens a WebSocket to ws://localhost:13337/ws/ssh
2. It sends an init payload with host, user, and private key
3. The CLI dials SSH to the target server, allocates a PTY (xterm-256color), and spawns a shell
4. All I/O is relayed bidirectionally over the WebSocket — including terminal resize events

The bridge binds exclusively to 127.0.0.1 and never exposes itself to the network. Your private key transits only between the browser tab and your local machine.

Native completions for bash, zsh, fish, and powershell. The install script configures this automatically. For manual setup:

# Bash
source <(pyxcloud completion bash)

# Zsh
source <(pyxcloud completion zsh)

# Fish
pyxcloud completion fish | source

# PowerShell
pyxcloud completion powershell | Out-String | Invoke-Expression

To persist, add the relevant line to your shell profile (~/.bashrc, ~/.zshrc, etc.).

A typical GitHub Actions workflow:

- name: Install PyxCloud CLI
  run: curl -sL https://github.com/PyxCloud/pyxcloud-cli/releases/latest/download/install.sh | bash

- name: Authenticate
  run: pyxcloud auth login --token ${{ secrets.PYXCLOUD_TOKEN }}

- name: Deploy
  run: pyxcloud arch deploy -p ${{ vars.PROJECT_ID }} -v ${{ github.ref_name }} --non-interactive

• PKCE OAuth2: Browser-based login uses Proof Key for Code Exchange — no client secrets stored
• Offline tokens: Sessions persist via Keycloak offline tokens with automatic refresh
• Shamir key recovery: Private keys are never stored whole — split shares require step-up re-authentication to reconstruct
• Local-only proxy: The shell bridge binds to 127.0.0.1 and cannot be reached from the network
• API tokens: Opaque pyxc_* tokens are exchanged for short-lived JWTs before each API call

The typed API clients in internal/api/gen/<contract> are generated with oapi-codegen (version pinned in go.mod via tools.go) from the pyx-backend OpenAPI contracts vendored in api/contracts/. The pinned pyx-backend commit is recorded in api/contracts/SOURCE.

# Re-vendor at the pinned SHA and regenerate (read access to pyx-backend needed:
# PYX_BACKEND_TOKEN, GH_TOKEN, GITHUB_TOKEN or `gh auth login`)
make sync-contracts generate

# Bump the pin to another ref, then regenerate and commit
scripts/sync-contracts.sh --ref main && make generate

.github/workflows/contracts-drift.yml fails when the vendored contracts or generated code differ from the pinned SHA, and reports (without failing) drift against pyx-backend main. Contracts that cannot be generated are listed, with the reason, in internal/api/gen/doc.go.

Copyright © 2026 CumulusCorp Inc. All Rights Reserved.

This software is distributed under a proprietary End User License Agreement (EULA). Reverse engineering, modification, and unauthorized redistribution are strictly prohibited. See the LICENSE file for details.