Spinifex Admin CLI

Complete reference for the Spinifex administration CLI. Manage accounts, nodes, VMs, and services.

cliadminreference

Overview

The spx binary is the central administration tool for managing your Spinifex infrastructure. It provides commands for cluster initialization, account management, node operations, VM lifecycle, and service control.

Binary location: /usr/local/bin/spx (binary install) or ~/Development/mulga/spinifex/bin/spx (source install)

All services in the Spinifex platform are managed through this single binary.

Instructions

Account Management

Create a new isolated account with an admin user and AdministratorAccess policy:

bash

spx admin account create --name myteam
export AWS_PROFILE=spinifex-myteam

List all accounts:

bash

spx admin account list

Node Management

List nodes in the cluster:

bash

spx get nodes

NAME    STATUS    IP              REGION           AZ               UPTIME   VMs
node1   Ready     127.0.0.1       ap-southeast-2   ap-southeast-2a  2m       0
node2   Ready     127.0.0.2       ap-southeast-2   ap-southeast-2a  2m       0
node3   Ready     127.0.0.3       ap-southeast-2   ap-southeast-2a  2m       0

Monitor Resources

bash

spx top nodes

Prints per-node CPU/memory usage and cluster-wide instance type availability.

Image Management

bash

spx admin images list
spx admin images import --name debian-12-arm64

Catalog imports verify the image against the catalog-declared SHA-256/SHA-512 digest before extraction. Use --file to import operator-supplied media (verification skipped — operator is responsible for integrity), or --force to re-download after a checksum mismatch.

Cluster Shutdown

Coordinated, phased shutdown of the entire cluster (API/UI → VMs → viperblock → predastore → NATS/daemon):

bash

spx admin cluster shutdown

Troubleshooting

Permission Denied Running Spinifex

The binary may not be executable. Fix permissions:

bash

chmod +x /usr/local/bin/spx

If you get permission errors during operations, ensure you're running with appropriate privileges. Some OVN and networking commands require sudo.

Services Fail to Start

Check the daemon logs for specific errors via systemctl/journalctl:

bash

systemctl status 'spinifex-*'
journalctl -u spinifex-daemon -f
journalctl -u 'spinifex-*' -f

Common causes include port conflicts, missing OVN configuration, or untrusted CA certificates.