Docs Dashboard Developers
Menu ⌃

CLI quickstart

Install the CLI, authenticate, register an SSH key, create a VM, wait for provisioning, and SSH in. About five minutes end-to-end. New to Metalhost? Read Concepts first for orgs, projects, wallets, and operations.

1. Install

macOS and Linux — one command:

curl -fsSL https://metalhost.net/install-cli.sh | bash

Installs the latest release to /usr/local/bin (or ~/.local/bin if you lack write access). Pin a version or change the install path: 

VERSION=v1.0.0-rc6 curl -fsSL https://metalhost.net/install-cli.sh | bash
INSTALL_DIR=~/.local/bin curl -fsSL https://metalhost.net/install-cli.sh | bash

Alternatives: download from GitHub Releases (Windows too), or go install github.com/AES-Services/metalhost-cli/cmd/metalhost@latest.

2. Authenticate

Interactive (first time)

The wizard writes your profile to ~/.config/metalhost/config.yaml: 

metalhost init

Choose paste an API key if you already minted one in the dashboard. The wizard also picks your default project and datacenter.

Automation (CI / scripts)

Set env vars — they override the profile on every command:

export METALHOST_ENDPOINT=https://api.metalhost.net
export METALHOST_API_KEY=mh_live_...
export METALHOST_PROJECT=projects/my-project
export METALHOST_REGION=datacenters/us-dal-1

metalhost auth whoami

Profile file

After init, your config looks like:

endpoint: https://api.metalhost.net
api_key: mh_live_...
organization: organizations/my-org
project: projects/my-project
region: datacenters/us-dal-1
format: table

Switch profiles with metalhost profile use NAME. Manage with metalhost profile list, create, set.

3. Discover your scope

Confirm identity and list projects before creating resources:

metalhost auth whoami -o json
metalhost project list
metalhost catalog datacenter list
metalhost catalog pricing quote --vcpus 2 --ram-gib 8 --cpu-class cascadelake --boot-disk-gib 80

4. Register an SSH key

Keys are project-scoped. Register once, reference on every VM: 

metalhost vm ssh-key create \
  --id laptop \
  --display-name "My laptop" \
  --public-key "$(cat ~/.ssh/id_ed25519.pub)"

metalhost get ssh-key

5. Create a VM and wait

VM create kicks off a background provision and returns an operations/… resource. --wait polls until it finishes: 

metalhost vm create \
  --hostname web-1 \
  --vcpus 2 \
  --ram-gib 8 \
  --cpu-class cascadelake \
  --image ubuntu-24-04 \
  --disk-size-gib 80 \
  --assign-public-ipv4 \
  --ssh-key-name projects/my-project/ssh-keys/laptop \
  --wait

Replace projects/my-project with your project from step 3. Required flags: --vcpus, --ram-gib, --cpu-class, and a boot source (--image or --boot-url with --disk-size-gib).

6. Read the VM and SSH in

metalhost vm get web-1 -o json | jq '.virtualMachine | {state, publicIpv4, linuxUsername}'

ssh ubuntu@$(metalhost vm get web-1 -o json | jq -r '.virtualMachine.publicIpv4')

Provisioning takes ~90 seconds. If state isn't RUNNING yet:

# if you saved the operation name from create output
metalhost ops wait operations/op_abc123
metalhost vm get web-1

7. Output formats

The CLI defaults to human-readable tables. For scripting:

metalhost vm list -o json
metalhost vm list -o yaml
metalhost vm list -q          # names only, one per line

8. Tear down

metalhost vm delete web-1 --yes --wait

Troubleshooting

ProblemWhat to check
endpoint is requiredRun metalhost init or set METALHOST_ENDPOINT
API key is requiredSet METALHOST_API_KEY or run metalhost auth login --api-key
Operation FAILEDmetalhost ops get operations/… — read errorMessage. Often wallet balance or capacity.
Can't SSHVM must be RUNNING; need publicIpv4 or use metalhost vm console
FailedPrecondition on createTop up the wallet in the dashboard

What's next