CLI: Instance Management

Overview

The agentmetal instance subcommand manages compute instances across your bare-metal providers. You can create, list, inspect, delete, and SSH into instances directly from the CLI.

Operations

Create an Instance

agentmetal instance create \
  --name my-web-server \
  --type cx31 \
  --image ubuntu-22.04 \
  --vpc vpc-abc123 \
  --subnet subnet-def456 \
  --ssh-key my-key

All create flags:

Flag	Required	Description
`--name`	Yes	Human-readable instance name
`--type`	Yes	Server type / plan (provider-specific)
`--image`	Yes	OS image identifier
`--vpc`	No	VPC ID to place the instance in
`--subnet`	No	Subnet ID within the VPC
`--ssh-key`	No	SSH key name or ID for access
`--security-group`	No	Security group IDs (repeatable)
`--user-data`	No	Path to cloud-init user data script

### List Instances

agentmetal instance list

Example output:

ID            NAME            TYPE   STATE    PRIVATE IP     PUBLIC IP
inst-a1b2c3   my-web-server   cx31   running  10.0.1.15      203.0.113.42
inst-d4e5f6   db-primary      cx41   running  10.0.2.10      203.0.113.55

Get Instance Details

agentmetal instance get inst-a1b2c3

Returns full instance details including spec, status, and metadata.

Delete an Instance

agentmetal instance delete inst-a1b2c3

Returns an operation ID for tracking the async deletion.

SSH into an Instance

agentmetal instance ssh inst-a1b2c3

Opens an interactive SSH session to the instance using the associated SSH key. Optionally pass --user root to override the default user.

InstanceSpec Fields

The full InstanceSpec accepted by the API:

Field	Type	Description
`type`	string	Server type identifier (e.g., `cx31`, `m3.small.x86`)
`image`	string	OS image identifier (e.g., `ubuntu-22.04`)
`vcpus`	int	Number of virtual CPUs
`memory_mb`	int	Memory in megabytes
`disk_gb`	int	Root disk size in gigabytes
`vpc_id`	string	VPC to attach the instance to
`subnet_id`	string	Subnet within the VPC
`security_groups`	string[]	List of security group IDs
`ssh_key_ids`	string[]	List of SSH key IDs for access
`user_data`	string	Base64-encoded cloud-init script

## Examples

Create and verify an instance:

# Create
agentmetal instance create \
  --name api-server \
  --type cx31 \
  --image ubuntu-22.04 \
  --vpc vpc-abc123 \
  --subnet subnet-def456 \
  --ssh-key deploy-key \
  --output json
Wait for provisioning, then check status
agentmetal instance get inst-xyz789
SSH in to verify
agentmetal instance ssh inst-xyz789

List as JSON for scripting:

agentmetal instance list --output json | jq '.[] | select(.status.state == "running") | .id'