CLI Reference¶

Complete reference for the machineuse-cli command-line interface.

Installation¶

The CLI is automatically installed with the machineuse package:

cd machineuse-api
poetry install

Global Options¶

machineuse-cli [OPTIONS] COMMAND [ARGS]

Option	Description	Default
`--url URL`	API server URL	`http://localhost:8000`
`--config FILE`	Config file path	-
`--verbose, -v`	Enable verbose output	False
`--quiet, -q`	Suppress output	False
`--help`	Show help message	-

Instance Commands¶

create¶

Create a new container instance.

machineuse-cli create [OPTIONS]

Option	Description	Default
`--image IMAGE`	Base image	`ubuntu:22.04`
`--memory GB`	Memory allocation	`2`
`--cpu CORES`	CPU cores	`2`
`--disk GB`	Disk space	`10`
`--node-preference NODE`	Preferred worker node	-
`--idle-timeout MINUTES`	Idle timeout	`30`
`--no-auto-snapshot`	Disable auto-snapshot	False

Example:

machineuse-cli create --image ubuntu:22.04 --memory 4 --cpu 2

list¶

List container instances.

machineuse-cli list [OPTIONS]

Option	Description
`--node NODE`	Filter by node
`--status STATUS`	Filter by status
`--format FORMAT`	Output format (table, json, csv)

Example:

machineuse-cli list --status running --format json

info¶

Get instance details.

machineuse-cli info INSTANCE_ID

delete¶

Delete an instance.

machineuse-cli delete INSTANCE_ID [OPTIONS]

Option	Description
`--force, -f`	Skip graceful shutdown

dormant¶

Make an instance dormant (snapshot and stop).

machineuse-cli dormant INSTANCE_ID

revive¶

Revive a dormant instance.

machineuse-cli revive INSTANCE_ID [OPTIONS]

Option	Description	Default
`--method METHOD`	Revival method (quick_start, full_restore)	`quick_start`

Cluster Commands¶

nodes list¶

List all worker nodes.

machineuse-cli nodes list [OPTIONS]

Option	Description
`--format FORMAT`	Output format

Example output:

ID          Status    Instances    CPU      Memory    
─────────────────────────────────────────────────────
worker-1    online    15/50        45%      62%
worker-2    online    23/50        67%      78%
worker-3    offline   0/50         -        -

cluster status¶

Show cluster overview.

machineuse-cli cluster status

Example output:

Cluster Status: healthy

Nodes: 3 (2 online, 1 offline)
Total Instances: 38
Running: 35
Dormant: 3

Resource Utilization:
  CPU: 56% average
  Memory: 70% average
  Disk: 45% average

metrics¶

Show metrics for a node or instance.

machineuse-cli metrics [OPTIONS]

Option	Description
`--node NODE`	Show node metrics
`--instance INSTANCE_ID`	Show instance metrics
`--period PERIOD`	Time period (1h, 24h, 7d)

Configuration Commands¶

config init¶

Generate configuration template.

machineuse-cli config init MODE [OPTIONS]

Argument	Description
`MODE`	Deployment mode: `single_node`, `control_plane`, `worker_node`

Option	Description
`-o, --output FILE`	Output file path

Example:

machineuse-cli config init single_node -o config.json

config validate¶

Validate a configuration file.

machineuse-cli config validate FILE

config show¶

Show current configuration.

machineuse-cli config show

Health Commands¶

health¶

Check service health.

machineuse-cli health

Example output:

Status: healthy
API: up
Storage: up
Messaging: up
Instances: 15 running

Bulk Commands¶

bulk dormant¶

Make multiple instances dormant.

machineuse-cli bulk dormant [OPTIONS]

Option	Description
`--node NODE`	Target specific node
`--status STATUS`	Target by status
`--dry-run`	Preview without executing

bulk delete¶

Delete multiple instances.

machineuse-cli bulk delete [OPTIONS]

Option	Description
`--node NODE`	Target specific node
`--status STATUS`	Target by status
`--force`	Skip confirmation

Output Formats¶

Most commands support multiple output formats:

# Table (default)
machineuse-cli list

# JSON
machineuse-cli list --format json

# CSV
machineuse-cli list --format csv

Environment Variables¶

Variable	Description
`MACHINEUSE_URL`	Default API URL
`MACHINEUSE_CONFIG`	Default config file

Exit Codes¶

Code	Description
0	Success
1	General error
2	Invalid arguments
3	Connection error
4	Not found

Shell Completion¶

Enable shell completion:

# Bash
eval "$(_MACHINEUSE_CLI_COMPLETE=bash_source machineuse-cli)"

# Zsh
eval "$(_MACHINEUSE_CLI_COMPLETE=zsh_source machineuse-cli)"

# Fish
_MACHINEUSE_CLI_COMPLETE=fish_source machineuse-cli | source