CLI reference¶

Reference for the otherix operator CLI - the command-line client for the Otherix control plane.

Hand-maintained

This page is written by hand against the cobra command tree. An autogenerated reference (make docs-cli from the cobra command tree) is planned; until then, treat the binary's own otherix <command> --help as the final authority if anything here drifts.

Global flags¶

These persistent flags are registered on the root command and inherited by every subcommand.

Flag	Default	Meaning
`--endpoint`	`http://localhost:8080` (only when neither config nor env supply one)	Control-plane base URL.
`--token`	(none)	API token; overrides `$OTHERIX_API_TOKEN` and any stored cluster token.
`--cluster`	(none)	Named cluster from the config file; overrides current-cluster.
`--config`	`$OTHERIX_CONFIG`, then `~/.otherix/config`	Config file path.

Most resource subcommands also accept an output flag, -o / --output, whose allowed values vary by command:

Mutating / detail commands: text (default), json.
get / list commands: add table and yaml (the YAML form projects an otherix/v1 manifest you can feed back to otherix create -f).
node commands: text / table / json (no yaml).

Auth resolution precedence¶

Endpoint and token are resolved independently, each through its own chain. The first layer that supplies a value wins:

Endpoint: --endpoint flag -> $OTHERIX_SERVER -> --cluster entry -> current-cluster entry -> error.
Token: --token flag -> $OTHERIX_API_TOKEN -> --cluster entry -> current-cluster entry -> error.

When --cluster is set, only that named cluster is consulted on the config layer (it does not fall back to current-cluster), mirroring kubectl --context.

Config file location¶

Resolved in order: --config flag -> $OTHERIX_CONFIG -> ~/.otherix/config. The file is a kubectl-style YAML credential store managed by otherix config; see that group to populate it.

otherix vm¶

Manage virtual machines (CP /v1/vms surface). VM positionals are names; UUID literals are rejected by the server.

vm create¶

Create a VM from an image source (async; returns a task id). <name> is the sole positional.

Flag	Default	Meaning
`--image-url`	(required)	Source image URL to download and boot from.
`--image-sha256`	(none)	Expected sha256, verified after download. Pins the image to exact content.
`--pull-policy`	`if-not-present`	`if-not-present` reuses a cached image for the URL; `always` forces a fresh re-fetch from `--image-url`. A mutable URL is not re-fetched under `if-not-present` (see the Create-and-manage-VMs guide).
`--arch`	(required)	`amd64` or `arm64`.
`--firmware`	(none)	Firmware name (mutually exclusive with `--firmware-id`).
`--firmware-id`	(none)	Firmware uuid (mutually exclusive with `--firmware`).
`--format`	(server default)	Disk format, e.g. `qcow2` or `raw`.
`--disk-gib`	image virtual size	Root disk size in GiB.
`--pool`	cluster default pool	Storage pool name or uuid.
`--node`	(scheduler picks)	Placement hint: node name or uuid.
`--network`	(none, SLIRP fallback)	Bridge network name or uuid to attach one NIC.
`--vcpus`	`2`	vCPU count (1..128).
`--memory-mib`	`2048`	Memory in MiB (128..524288).
`--user-data`	(none)	Path to a `#cloud-config` user-data YAML, or `-` for stdin. Mutually exclusive with `--no-cloud-init`.
`--network-config`	(none)	Path to a cloud-init network-config YAML (netplan v2), or `-` for stdin. Mutually exclusive with `--no-cloud-init`.
`--no-cloud-init`	`false`	Explicitly disable cloud-init. Mutually exclusive with `--user-data` and `--network-config`.
`--wait`	`false`	Block until the task reaches terminal status.
`--wait-timeout`	`10m`	Max wait when `--wait` is set.

otherix vm create web-1 --image-url https://example.com/ubuntu.qcow2 \
  --arch arm64 --vcpus 2 --memory-mib 2048 --wait

vm get¶

Show a VM's projection. -o text|json|yaml (default text).

otherix vm get web-1 -o yaml

vm list¶

Cursor-paginated list of visible VMs.

Flag	Default	Meaning
`--pool`	(none)	Filter by pool name or uuid.
`--node`	(none)	Filter by current-location node name or uuid.
`--status`	(none)	Filter by status.
`--limit`	`20`	Page size (1..200).
`--cursor`	(none)	Opaque cursor from a previous page.
`-o, --output`	`table`	`table\|json\|yaml`.
`--show-ids`	`false`	Include VM UUIDs in the table.

otherix vm list --status running --limit 50

vm delete¶

Delete a VM (async). Prompts when stdin is a TTY unless --force.

Flag	Default	Meaning
`--force`	`false`	Skip the confirmation prompt.
`--wait`	`false`	Block until terminal status.
`--wait-timeout`	`10m`	Max wait when `--wait` is set.

otherix vm delete web-1 --force --wait

vm lifecycle (sync)¶

pause, resume, and reset are synchronous (single QMP call) and take a VM positional plus -o text|json (default text).

vm pause <vm> - QMP stop (vCPUs freeze).
vm resume <vm> - QMP cont.
vm reset <vm> - QMP system_reset (hard reset, runtime identity preserved).

otherix vm pause web-1

vm lifecycle (async)¶

start, stop, poweroff, and reboot are asynchronous; each takes a VM positional plus --wait / --wait-timeout (10m).

vm start <vm> - boot the QEMU process; sets desired_phase=running.
vm stop <vm> - graceful ACPI shutdown. --force short-circuits to the poweroff endpoint (hard shutdown) instead.
vm poweroff <vm> - hard power-off (QMP quit, then SIGKILL).
vm reboot <vm> - graceful stop+start cycle (PID changes).

otherix vm stop web-1 --force --wait   # hard poweroff via --force

vm console¶

Attach to a VM's serial console interactively (the VM must be running). Press Ctrl+] to bring up a local close prompt. No flags beyond the globals.

otherix vm console web-1

vm logs¶

Stream a VM's serial console output (kubectl-style).

Flag	Default	Meaning
`--tail`	`-1` (all)	Trailing lines from history (`0` = none).
`-f, --follow`	`false`	Keep streaming live output after the history flush.

otherix vm logs web-1 --tail 100 --follow

vm migrate¶

Live-migrate a VM to another node (async). Every migration is a full storage migration (the disks cross the wire); the default is a live cutover, --offline stops the VM, copies it cold, and starts it on the target. With no --node the scheduler picks a different eligible node. Returns a task and a first-class migration resource - poll it with otherix migration get. See the Live migration guide.

Flag	Default	Meaning
`--node`	(scheduler picks a different node)	Target node name.
`--pool`	cluster default pool	Target storage pool name on the target node.
`--offline`	`false`	Stop+copy+start instead of a live cutover.
`--bandwidth`	(uncapped)	Transfer-rate cap, e.g. `100m`, `1g`, or raw bytes/s.
`--max-downtime`	(server default)	Live-cutover downtime budget in milliseconds.
`--allow-postcopy`	`false`	Allow post-copy escalation if pre-copy will not converge.
`--wait`	`false`	Block until the backing task reaches terminal status (client-side bound only; the migration runs server-side regardless).
`--wait-timeout`	`10m`	Max wait when `--wait` is set.

otherix vm migrate web-1                 # live, scheduler picks the target
otherix vm migrate web-1 --node node-3   # live, to a specific node
otherix vm migrate web-1 --offline       # stop, move cold, start on target

otherix ssh¶

SSH into a VM by name through the control plane, with no public IP on the VM. See SSH access to VMs.

ssh¶

Open an interactive SSH session. Mints a short-lived guest certificate and tunnels through the broker (gateway for overlay VMs, CP relay for bridge VMs). The VM must have been created with --ssh-ingress.

Flag	Default	Meaning
`--login`	`root`	Guest login user.

otherix ssh web-1
otherix ssh web-1 --login deploy

otherix ssh proxy <vm> <port> is the internal ProxyCommand primitive and is not run by hand.

otherix forward¶

Forward a local TCP port to a VM's port through the control plane (arbitrary L4: databases, web UIs, metrics, a raw SSH port). See Port forwarding.

forward¶

Open a local listener and splice each connection to the VM's guest port. Each connection is brokered independently. The positional port spec follows kubectl port-forward:

otherix forward <vm-name> [LOCAL_PORT:]REMOTE_PORT

REMOTE_PORT - binds the same port number locally.
LOCAL_PORT:REMOTE_PORT - pins a specific local port (override a busy default).
:REMOTE_PORT - picks an ephemeral local port (printed on start).

Flag	Default	Meaning
`--address`	`127.0.0.1`	Bind host for the local listener (host only, e.g. `0.0.0.0`).
`-L, --listen`	`127.0.0.1:0`	Local `host:port` shortcut; alternative to `--address` plus a local port in the spec. Mutually exclusive with both.

otherix forward db-1 5432           # local 5432 -> db-1:5432; then: psql -h 127.0.0.1 -p 5432
otherix forward db-1 15432:5432     # pin a local port when 5432 is busy
otherix forward web-1 8080 --address 0.0.0.0   # expose on the LAN

otherix lb¶

Load balancers front a label-selected pool of VMs with active health checks. Addressed by name. See Load balancers.

lb create¶

Create a load balancer. Backends are the VMs whose labels match --selector (labels are set at otherix vm create --label).

Flag	Default	Meaning
`--port`	(required)	Guest TCP port traffic is sent to (1..65535).
`--selector`	(required)	Label match, `k=v[,k=v...]` (>=1 term).
`--health-port`	follow `--port`	TCP port the health probe dials.
`--health-interval`	`10`	Seconds between probes (1..300).
`--health-timeout`	`2`	Per-probe connect timeout, seconds (1..60).
`--health-healthy-threshold`	`2`	Consecutive successes to mark a backend healthy (1..10).
`--health-unhealthy-threshold`	`3`	Consecutive failures to mark a backend unhealthy (1..10).
`-o, --output`	`text`	`text` or `json`.

otherix lb create web-lb --port 80 --selector app=web \
  --health-port 8080 --health-interval 5

lb list¶

List load balancers. Columns: NAME PORT SELECTOR STATUS TARGETS. STATUS is healthy / degraded / unhealthy / no_backends; TARGETS is <healthy>/<total> backends.

Flag	Default	Meaning
`--limit`	`20`	Page size (1..200).
`--cursor`		Opaque cursor from a previous page.
`-o, --output`	`table`	`table`, `json`, or `yaml`.
`--show-ids`	`false`	Include UUIDs.

otherix lb list

lb get¶

Show one load balancer, including per-backend health (healthy true/false, or unknown for a warming backend). -o yaml emits an apply-ready manifest.

otherix lb get web-lb
otherix lb get web-lb -o yaml

lb update¶

Update mutable fields. --selector replaces the whole selector.

Flag	Default	Meaning
`--port`		New traffic port.
`--selector`		New selector (replaces the previous one).
`--health-*`		Any of the health-check flags above.

otherix lb update web-lb --selector app=web,tier=frontend

lb delete¶

Delete a load balancer.

Flag	Default	Meaning
`--force`	`false`	Skip the confirmation prompt.

otherix lb delete web-lb --force

lb connect¶

Open a local listener that balances each connection over the healthy backend pool. A long-lived listener load-balances because every connection re-brokers.

Flag	Default	Meaning
`-L, --listen`	`127.0.0.1:0`	Local `host:port` to listen on.

otherix lb connect web-lb -L 127.0.0.1:8080

otherix ingress-grant¶

Scoped, optionally time-boxed access to a named set of (VM, port) targets for a party with no Otherix account. Requires the vm:ingress-grant permission. See Grant external access.

ingress-grant create¶

Create a grant and print its one-time bundle.

Flag	Default	Meaning
`--vm`	(required)	`host:port[,port...]`, repeatable (one VM per flag). Port 22 = SSH.
`--login`	`root`	Guest login applied to every VM.
`--source-ip`		Pin the caller's source IP or CIDR (fail-closed).
`--ttl`	(never)	Lifetime, e.g. `168h`, `720h`. Omit = never expires.
`--user`		Free-text recipient label.
`-o, --output`	`text`	`text`, `json`, or `yaml`.

otherix ingress-grant create acme --vm web-1:22 --vm db-1:5432,8080 \
  --login deploy --ttl 168h --source-ip 203.0.113.10/32

ingress-grant add-vm / remove-vm¶

Add or remove a VM on an existing grant.

otherix ingress-grant add-vm acme cache-1:6379 --login deploy
otherix ingress-grant remove-vm acme cache-1

ingress-grant list / get / revoke / delete¶

Manage grants. revoke disables a grant immediately (the kill switch); delete removes it.

otherix ingress-grant list
otherix ingress-grant get acme
otherix ingress-grant revoke acme
otherix ingress-grant delete acme

otherix migration¶

Inspect VM migrations (CP /v1/migrations surface). Migrations are created by otherix vm migrate, never here; this group is read-only plus a best-effort cancel.

migration list¶

Cursor-paginated list of migrations visible to the caller.

Flag	Default	Meaning
`--vm`	(none)	Filter by VM uuid.
`--node`	(none)	Filter by node uuid (source or target).
`--limit`	`20`	Page size (1..200).
`--cursor`	(none)	Opaque cursor from a previous page.
`-o, --output`	`table`	`table\|json\|yaml`.

otherix migration list --vm <vm-uuid>

migration get¶

Show a migration's projection (<id> positional). After a live migration this includes a statistics: section - ram / disk bytes and total_time / downtime / setup_time. -o text|json|yaml (default text); text renders human units, JSON keeps raw bytes and milliseconds.

otherix migration get <migration-id>

migration cancel¶

Cancel a migration, best-effort (<id> positional). Returns the current task state; leaves the VM safely on one node or the other, never split across both. No flags beyond the globals.

otherix migration cancel <migration-id>

otherix snapshot¶

Disk-only, crash-consistent, content-addressed VM snapshots. Snapshots are created through vm snapshot (a VM sub-resource action) and managed through the top-level snapshot group. See the Snapshots guide and concept page.

vm snapshot¶

Capture a snapshot of <vm> (CP POST /v1/vms/<vm>/snapshots, async).

Flag	Default	Meaning
`--name`	`snap<unix_seconds>`	Snapshot name, unique within the VM.
`--description`	(unset)	Optional free-text description.
`--artifact-pool`	cluster default	Artifact pool that sets the replication factor for this snapshot.
`--wait`	`false`	Block until the capture task reaches a terminal status.
`--wait-timeout`	`10m`	Max time the CLI blocks when `--wait` is set (the snapshot keeps producing server-side regardless).

otherix vm snapshot web-1 --name golden --wait
otherix vm snapshot web-1 --artifact-pool artifacts

snapshot list / get / delete¶

otherix snapshot list [--vm <name>] [--status <status>]
otherix snapshot get <id>
otherix snapshot delete <id>      # async; reclaims orphaned blobs automatically

vm create --from-snapshot¶

Recreate a fresh VM from a snapshot instead of an image URL (mutually exclusive with --image-url). Architecture, format, and firmware come from the snapshot manifest, so --arch and the image flags are not passed. The recreate can run on any node; an absent blob is pulled peer-to-peer before boot.

otherix vm create web-2 --from-snapshot <snapshot-id>

otherix artifact-pool¶

Cluster-level content-addressed stores that set the replication factor for the snapshots tagged into them. Every authenticated role can read them; create, update, and delete are admin-only. See the Snapshots guide.

artifact-pool create¶

Flag	Default	Meaning
`--replication-factor`	`1`	Durability target: an integer `>= 1`, or `all` for every member. The control plane keeps each blob on that many live nodes and re-replicates after a node loss.
`--members`	`all`	Which nodes may back the pool: `all` or a comma-separated node-name list.
`-o, --output`	`text`	`text` or `json`.

otherix artifact-pool create artifacts --replication-factor 2
otherix artifact-pool create artifacts --replication-factor all

artifact-pool list / get / update / delete¶

otherix artifact-pool list
otherix artifact-pool get artifacts
otherix artifact-pool update artifacts --replication-factor 3   # re-replicates existing snapshots immediately
otherix artifact-pool update artifacts --members node-a,node-b
otherix artifact-pool delete artifacts                          # refused while snapshots still reference it

The pool name is immutable; update changes only --replication-factor and/or --members (at least one required).

otherix pool¶

Manage storage pools (CP /v1/storage-pools surface). Multi-instance: one pool name may live on many nodes. create / delete are admin-only.

pool list¶

Cursor-paginated list of pool instances (one row per node).

Flag	Default	Meaning
`--node`	(none)	Filter by owning node name or uuid.
`--type`	(none)	Filter by pool type (`local_dir`).
`--limit`	`20`	Page size (1..200).
`--cursor`	(none)	Opaque cursor.
`-o, --output`	`table`	`table\|json\|yaml`.
`--show-ids`	`false`	Include instance UUIDs in the table.

otherix pool list --node node-dev

pool get¶

Dual-shape: a name positional returns the aggregated PoolConceptView; a UUID positional returns the flat per-node instance. -o text|json|yaml (default text).

otherix pool get default        # aggregated by name
otherix pool get <pool-uuid>    # flat per-instance

pool create¶

Register one (name, node) pool instance. Admin-only. Not idempotent: a duplicate (name, node) is an error.

Flag	Default	Meaning
`--node`	(required)	Owning node name.
`--path`	(required)	Filesystem path on the owning node.
`--type`	`local_dir`	Pool type.
`--wait`	`false`	Poll until reconciliation reaches `ready`/`failed` (60s timeout).
`-o, --output`	`text`	`text\|json`.
`--show-ids`	`false`	Include the pool UUID in text output.

otherix pool create pool-dev --node node-dev --path /var/lib/otherix/pools/default --wait

pool delete¶

Delete a pool by name or UUID. Admin-only. Refuses with 409 conflict when vm_disks still reference the pool (no force-delete by design). Prompts when stdin is a TTY unless --force.

Flag	Default	Meaning
`--force`	`false`	Skip the confirmation prompt.
`--node`	(none)	Delete the instance on this node (disambiguates a multi-instance name).
`-o, --output`	`text`	`text\|json`.

otherix pool delete default --node node-1

otherix network¶

Manage networks (CP /v1/networks surface). Names are globally unique; every authenticated role can read, admin alone may create / delete.

network create¶

Create one cluster-wide network. Admin-only.

Flag	Default	Meaning
`--type`	`bridge`	`bridge` or `overlay`.
`--bridge-name`	(required for `bridge`)	Host bridge interface name.
`--managed`	`false`	Control plane manages the bridge lifecycle.
`--egress`	`none`	Managed egress mode: `none` or `nat`.
`--subnet`	(none)	Egress subnet in CIDR form (required for `--egress nat` and for `--type overlay`).
`--gateway`	(derived)	Gateway IP inside `--subnet`.
`--mtu`	server `1500`	Link MTU (68..9216).
`--vlan`	(untagged)	VLAN tag (1..4094).
`--dhcp`	`false`	Enable CP-IPAM + DHCP responder (overlay only; requires `--egress nat` `--subnet`).
`-o, --output`	`text`	`text\|json`.
`--show-ids`	`false`	Include the network UUID in text output.

--type overlay requires --subnet and forbids the bridge-only flags (--bridge-name, --mtu, --vlan, --egress, --managed, --gateway).

otherix network create net-dev --bridge-name br0
otherix network create net-nat --bridge-name br-nat --managed --egress nat --subnet 10.10.0.0/24

network list¶

Cursor-paginated list.

Flag	Default	Meaning
`--type`	(none)	Filter by type (`bridge`).
`--limit`	`20`	Page size (1..200).
`--cursor`	(none)	Opaque cursor.
`-o, --output`	`table`	`table\|json\|yaml`.
`--show-ids`	`false`	Include network UUIDs in the table.

otherix network list

network get¶

Show a network and its per-node materialisation status. Positional accepts a name or UUID (a name is resolved client-side). -o text|json|yaml (default text).

otherix network get net-dev

network delete¶

Delete a network by name or UUID. Admin-only. Refuses with 409 conflict when vm_nics still reference it (no force-delete). Prompts when stdin is a TTY unless --force.

Flag	Default	Meaning
`--force`	`false`	Skip the confirmation prompt.
`-o, --output`	`text`	`text\|json`.

otherix network delete net-dev --force

otherix node¶

Browse cluster nodes (CP /v1/nodes surface), manage the ingress-gateway role, and mint join-token bundles. admin / operator callers see the full Node projection; other roles see the reduced summary. A node's roles are derived: hypervisor when it owns a storage pool, gateway when the gateway role is assigned - a co-located node reports both. See the Ingress gateways guide for the operator flow.

node list¶

Cursor-paginated list.

Flag	Default	Meaning
`--architecture`	(none)	Filter by `amd64` / `arm64`.
`--status`	(none)	Filter by status.
`--role`	(none)	Filter by role: `hypervisor` / `gateway`.
`--limit`	`20`	Page size (1..200).
`--cursor`	(none)	Opaque cursor.
`--output` (`-o`)	`table`	`table\|json\|yaml`.
`--show-ids`	`false`	Include node UUIDs in the table.

otherix node list --architecture arm64
otherix node list --role gateway

node get¶

Show a node's projection. <node> is a name. --output (-o) text|json|yaml (default text), --show-ids includes the UUID.

otherix node get node-dev

node gateway¶

Assign or remove the ingress-gateway role on a node (node:manage). Name-only, idempotent 200. Enabling on a hypervisor node co-locates a gateway (the node keeps hosting VMs); see the Ingress gateways guide.

otherix node gateway enable node-1
otherix node gateway disable node-1

node join-token¶

Mint, list, and revoke node-agent bootstrap tokens (admin only).

join-token create¶

Mint a fresh token bundle (plaintext token + cluster CA fingerprint), printed exactly once.

Flag	Default	Meaning
`--kind`	`node`	Join kind: `node` (hypervisor) or `gateway` (standalone ingress gateway). Cluster-replica tokens use `otherix cluster join-token create`.
`--ttl`	`1h`	Token validity (1m..24h).
`--max-uses`	`0` (server default of 1 = single-use)	Consumption cap. `0` and an omitted value both default to single-use; a truly unlimited token cannot be minted from the CLI/API.
`--node-name`	(none)	Bind token to a node identity (forces single-use).
`--output`	`text`	`text\|json`.

otherix node join-token create --node-name node-dev --ttl 10m
otherix node join-token create --kind gateway --node-name gw-1 --ttl 10m

join-token list¶

Flag	Default	Meaning
`--include-expired`	`false`	Surface expired tokens.
`--limit`	`20`	Page size (1..200).
`--cursor`	(none)	Opaque cursor.
`--output`	`table`	`table\|json`.

otherix node join-token list --include-expired

join-token revoke¶

Revoke an unconsumed token by id (UUID positional). No flags beyond the globals.

otherix node join-token revoke <token-id>

join-token consumptions¶

List the consumption audit trail for a token (UUID positional).

Flag	Default	Meaning
`--limit`	`20`	Page size (1..200).
`--cursor`	(none)	Opaque cursor.
`--output`	`table`	`table\|json`.

otherix node join-token consumptions <token-id>

otherix cluster¶

Manage cluster-wide settings (CP /v1/cluster surface). Mutating commands require admin (cluster:manage).

cluster get-default-pool¶

Show the cluster default pool reference. --output text|json (default text). Prints an informational line and exits 0 when unset.

otherix cluster get-default-pool

cluster set-default-pool¶

Set the cluster default pool by NAME (<name> positional). UUIDs are rejected. --output text|json.

otherix cluster set-default-pool default

cluster unset-default-pool¶

Clear the default pool reference. Prompts when stdin is a TTY; non-interactive use requires --force.

otherix cluster unset-default-pool --force

cluster default-artifact-pool¶

The artifact-pool analogue of the default-pool commands: a vm snapshot that omits --artifact-pool is tagged into this pool and inherits its replication factor. set/unset are admin-only.

otherix cluster get-default-artifact-pool
otherix cluster set-default-artifact-pool artifacts
otherix cluster unset-default-artifact-pool --force

cluster default-network¶

The network analogue of the default-pool commands. When a default network is set, otherix vm create without --network attaches one NIC to it; when unset, a VM created without --network has no NIC. The name must resolve to an existing bridge network. set/unset are admin-only (cluster:manage); get is open to every role and prints an informational line and exits 0 when unset.

otherix cluster get-default-network
otherix cluster set-default-network default
otherix cluster unset-default-network --force

cluster join-token create¶

Mint a kind=cluster (HA-grow) join token used to add a new control-plane replica. Admin-only; the bundle (token plaintext + cluster CA fingerprint) is printed exactly once.

Flag	Default	Meaning
`--ttl`	`1h`	Token validity (1m..24h).
`--max-uses`	`0` (server default of 1 = single-use; cap 16 for cluster tokens)	Consumption cap.
`--output`	`text`	`text\|json`.

otherix cluster join-token create --max-uses 3

cluster member list¶

List etcd cluster members (id, name, learner flag, peer URLs). --output text|json (default text).

otherix cluster member list

cluster member remove¶

Remove an etcd member by hex id (<id> positional). Prompts when stdin is a TTY; non-interactive use requires --force.

otherix cluster member remove <hex-id> --force

otherix user¶

Manage user accounts (CP /v1/users surface). A username is the account's unique identity and login credential: lowercase letters, digits, and interior hyphens (3..32). email and display_name are optional. Create/list/delete and set-role require admin; whoami works for any role. Passwords are never passed as a flag value - they are read from a no-echo prompt or, with --password-stdin, one line from stdin.

user create¶

Create a user. <username> is positional.

Flag	Default	Meaning
`--role`	(required)	`admin` / `operator` / `developer` / `viewer`.
`--email`	(none)	Optional contact email.
`--display-name`	(none)	Optional human label.
`--password-stdin`	`false`	Read the password from stdin instead of prompting.

otherix user create dev-user --role developer
otherix user create ci-bot --role viewer --password-stdin <<<"$PW"

user list¶

Cursor-paginated list. --output table|json, --limit, --cursor, plus an optional --username exact-match filter.

otherix user list

user get¶

Show one user. <username> is positional. --output table|json|yaml.

otherix user get dev-user

user set-role¶

Change a user's role (admin only). otherix user set-role <username> <role>.

otherix user set-role dev-user operator

user set-password¶

Reset a user's password. <username> is positional; the new password is read from a no-echo prompt, or from stdin with --password-stdin.

otherix user set-password dev-user
otherix user set-password dev-user --password-stdin <<<"$NEW_PW"

user delete¶

Soft-delete a user (<username> positional). Refused while the user still owns resources (VMs, snapshots); transfer or remove those first.

otherix user delete dev-user

user whoami¶

Print a one-line identity summary of the calling user (username, role, id). Works for any role; -o json / -o yaml emit the full user object.

otherix user whoami
# admin (role: admin, id: fdee0856-a462-4f67-819a-f8f7002e598f)

otherix api-token¶

Mint, list, and revoke the otx_* API tokens that authenticate the CLI and automation (CP /v1/users/.../api-tokens surface). Every authenticated role manages its own tokens; an admin can act on another user's tokens with --user <username>. The plaintext token is shown exactly once, on create, and is never passed as a flag or argument.

api-token create¶

Mint a token. <name> is positional.

Flag	Default	Meaning
`--ttl`	(never expires)	Relative lifetime: `90d`, `720h`, `30d12h`.
`--user`	(yourself)	Mint on behalf of this user (admin only).
`-o`	`text`	Output format: `text` / `json` / `yaml` (all include the plaintext once).

otherix api-token create ci-bot
otherix api-token create ci-bot --ttl 90d
otherix api-token create deploy --user alice

The command prints the plaintext token once - copy it immediately:

api token created - copy it now, it will not be shown again:

  otx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  name:       ci-bot
  prefix:     otx_xxxx
  expires_at: never
  id:         ...

api-token list¶

Cursor-paginated list. --output table|json|yaml, --limit, --cursor, plus --user <username> (admin) and --include-revoked (revoked tokens are hidden by default). The STATUS column is active, expired, or revoked.

otherix api-token list
otherix api-token list --include-revoked

api-token revoke¶

Revoke a token by its prefix (the otx_xxxx shown by list), resolved to its id client-side. If a prefix is ambiguous, pass the full token id instead. --user <username> (admin) targets another user; --force skips the confirmation prompt. Revoke is immediate and idempotent.

otherix api-token revoke otx_xxxx
otherix api-token revoke otx_xxxx --user alice --force

otherix config¶

Manage CLI cluster credentials in the kubectl-style YAML store at $OTHERIX_CONFIG / ~/.otherix/config.

config add cluster¶

Log in to a CP, mint a long-lived otx_* API token, and persist it as a named cluster.

Flag	Default	Meaning
`--name`	(required)	Cluster name.
`--server`	`$OTHERIX_SERVER`	CP base URL.
`--login`	`$OTHERIX_LOGIN`	Operator username.
`--password`	`$OTHERIX_PASSWORD`	Operator password.
`--set-current`	`true`	Make this the current cluster.
`--force`	`false`	Overwrite an existing entry (revokes the old token server-side).

Missing required values are prompted interactively when stdin is a TTY.

otherix config add cluster --name dev --server https://cp.dev:8080 --login admin

config list¶

List configured clusters (NAME / SERVER / CURRENT). No flags beyond the globals.

otherix config list

config use¶

Set the current cluster (<name> positional).

otherix config use dev

config remove¶

Remove a cluster from the config (<name> positional). Prompts when stdin is a TTY; non-interactive use requires --force.

Flag	Default	Meaning
`--force`	`false`	Skip the confirmation prompt.

otherix config remove dev --force

config show¶

Print a cluster's details (token masked). [name] is optional and defaults to the current cluster.

Flag	Default	Meaning
`--show-token`	`false`	Reveal the plaintext API token.

otherix config show dev --show-token

Manifest commands¶

Top-level create / delete apply multi-document otherix/v1 YAML manifests (Network, StoragePool, VM). Documents are separated by ---.

otherix create -f¶

Create resources from manifests, ordered Network -> StoragePool -> VM so name references resolve. Best-effort: a failed document does not stop the rest, and a non-zero exit signals any failure.

Flag	Default	Meaning
`-f, --filename`	(required)	Manifest file path, or `-` for stdin (repeatable).
`--dry-run`	`false`	Print the plan without creating anything.
`--wait`	`false`	Block until every async resource (VM tasks, pool reconciliation) is ready.
`--wait-timeout`	`5m`	Max wait when `--wait` is set.

otherix create -f cluster.yaml --wait

otherix delete -f¶

Delete the resources named by manifests, in reverse create order (VM -> StoragePool -> Network). Existing delete blockers are reported and skipped, never forced.

Flag	Default	Meaning
`-f, --filename`	(required)	Manifest file path, or `-` for stdin (repeatable).
`--force`	`false`	Skip the confirmation prompt.
`--dry-run`	`false`	Print the plan without deleting anything.

otherix delete -f cluster.yaml --force