command reference

every console command: flags, defaults, and the errors you may see. this is the lookup table; the topic pages are the tour.

running commands

every command runs the same way in two places:

$ ssh dashboard@ironwire.sh list
NAME             STATUS     IMAGE        IP           FLAGS  URL
web              running    ubuntu       10.77.0.2    -      https://web.sam.ironwire.xyz

SSH one-shots from your own computer: ssh dashboard@ironwire.sh <command…>. no command opens the interactive dashboard instead. see connecting.
the ironwire CLI inside a machine: ironwire <command…>, same verbs, same output. see the CLI.

note all flags take the --flag=value form. --mem 2G with a space is not accepted. (env additionally accepts -m=<name> as shorthand for --machine=.)

JSON mode: set IRONWIRE_FMT=json in the command's environment (the ironwire CLI forwards it). typed shapes are noted below; every other command wraps its text as {"ok":true,"message":"<text>"}, and errors come back as {"ok":false,"error":"<msg>"}. see orchestration.

machines

$ ssh dashboard@ironwire.sh create web --mem=2G --drive
created web
  url: https://web.sam.ironwire.xyz
  ssh: ssh sam+web@ironwire.sh

`create <name> [--cpu=<cores|max>] [--mem=<size|max>] [--disk=<size|max>] [--restart=…] [--drive] [--image=<id>] [--port=<guest|none>] [--publish=<public:guest>]`

alias: new

create a machine. <name> is required: lowercase, starting with a letter, then letters/digits/hyphens, 2 to 31 characters; dashboard is reserved. sizes accept 5G, 512M, a bare MiB number, or max (fill what's left in your budget; for --cpu, your per-machine ceiling).

Flag	Value	Default	Meaning
`--cpu=`	cores or `max`	platform default	vCPU cores.
`--mem=`	size or `max`	platform default	memory.
`--disk=`	size or `max`	platform default	disk.
`--restart=`	policy	platform default	restart policy.
`--image=`	image id	`ubuntu`	guest image; see `images`.
`--drive`	(boolean)	off	attach your shared drive, creating it at the default size if you don't have one.
`--port=`	guest port or `none`	`8000`	guest port behind the machine's main HTTPS URL; `none` (or `off`) = no public URL.
`--publish=`	`<public>:<guest>`	—	extra HTTPS port mapping; repeatable.

errors you may see: invalid name (lowercase, a-z0-9-, 2-31 chars), name "<name>" is taken. requests over your budget are rejected with the limit and what you asked for.

JSON: {"ok":true,"machine":{…}} with name, ip, status, policy, image, url, ports, ssh, and sizes.

more: machines & lifecycle.

`copy <source> <new-name>`

alias: clone

clone a machine's disk into a new machine. the source must be paused or stopped first; the copy inherits size, restart policy, and drive attachment. missing arguments give copy: need <source> <new-name>; a busy source gives cannot copy "<name>" while it is <status> — pause or stop it first (copy clones a settled disk).

JSON: {"ok":true,"machine":{…}}. more: machines & lifecycle.

`images`

list the guest images you can create machines on: one block per image with its id, label, on-disk size, and description. no arguments or flags.

JSON: {"ok":true,"images":[{"id","label","bytes","info"}]}. more: machines & lifecycle.

`list`

alias: ls

list your machines as a table: NAME STATUS IMAGE IP FLAGS URL. the FLAGS column shows O for can-orchestrate, P for delete-protected, - for neither. with no machines it prints no machines.

JSON: {"ok":true,"machines":[…]}. more: machines & lifecycle.

`info <name>`

show one machine: status, IP, size, restart policy, URL, SSH endpoint, orchestration and protection switches, published ports, and reachability hints. missing name: info: need a machine name.

JSON: {"ok":true,"machine":{…},"network":{…},"system_version":…}. more: machines & lifecycle.

`resize <name> [--cpu=<cores|max>] [--mem=<size|max>] [--disk=<size|max>]`

change a machine's size; the new size applies on the next restart. omitted flags keep their current value. disk can only grow.

Flag	Value	Default	Meaning
`--cpu=`	cores or `max`	keep current	vCPU cores.
`--mem=`	size or `max`	keep current	memory.
`--disk=`	size or `max`	keep current	disk (grow only).

at least one flag is required: resize: pass at least one of --cpu/--mem/--disk. shrinking disk gives disk can only grow (<cur> MiB now, requested <n> MiB).

JSON: {"ok":true,"machine":{…},"note":"applies on next restart"}. more: machines & lifecycle.

`stats <name> [--range=1h|24h|7d|30d]`

show a machine's current CPU, memory, and disk usage plus a history table.

Flag	Value	Default	Meaning
`--range=`	`1h`, `24h`, `7d`, `30d`	`1h`	history window.

an unknown window gives unknown range "<w>" (use 1h, 24h, 7d, 30d). if the machine isn't running or metrics are still warming up, the current block says now: no data (machine not running or metrics still warming up).

JSON: {"ok":true,"stats":{"range","from","to","series":[…],"current":{…}}}. more: machines & lifecycle.

power & lifecycle

$ ssh dashboard@ironwire.sh stop web
stopped web
$ ssh dashboard@ironwire.sh start web
started web

`stop <name>`

power a machine off; its name, IP, and disk are kept. stopping a machine that isn't running gives <name> is not running (it is <status>). more: machines & lifecycle.

`start <name>`

boot a stopped machine on its same IP. starting a running machine gives <name> is already running. more: machines & lifecycle.

`restart <name>`

alias: reboot

stop then start the machine. this is how a pending resize, env-var change, or drive attach/detach takes effect. more: machines & lifecycle.

`pause <name>`

freeze the whole machine: RAM and processes are snapshotted to disk. a paused machine frees its vCPU and memory back to your budget. more: machines & lifecycle.

`resume <name>`

restore a paused machine exactly where it left off. resuming a machine that isn't paused gives <name> is not paused (it is <status>). more: machines & lifecycle.

`rm <name>`

delete a machine permanently; the disk is gone. delete protection blocks everyone, including you, until you turn it off: machine "<name>" is delete-protected; turn protection off first. more: machines & lifecycle.

networking

$ ssh dashboard@ironwire.sh ports web main 3000
443:  https://web.sam.ironwire.xyz → vm port 3000
published: (none)

`connect <name>`

alias: ssh

open an interactive shell into a machine. unknown machines give machine "<name>" not found. you can also SSH straight in with ssh <handle>+<machine>@ironwire.sh; see connecting.

`ports <name> [main <guest|none> | publish <public:guest> | unpublish <public>]`

manage a machine's HTTPS ports. with no subcommand it lists them. subcommand aliases: add = publish; rm = remove = unpublish.

ports <name>: show the main URL mapping and every published port.
ports <name> main <guest-port|none>: point the machine's bare HTTPS URL at a guest port, or none to turn the public URL off.
ports <name> publish <public>:<guest>: publish an extra HTTPS port.
ports <name> unpublish <public>: remove a published port.

changes apply live without a restart. errors you may see: port <n> is not published on <name>, public port <n> is reserved by the platform. more: networking.

`domain <name> [status | set <fqdn> | rm]`

attach your own domain to a machine. subcommand aliases: rm = clear = remove; with no subcommand, status is shown. set requires a subdomain you control; after setting, create a CNAME to the shown target and it goes live automatically.

errors you may see: "<fqdn>" is not a valid domain name, "<fqdn>" must be a subdomain (e.g. app.example.com) — an apex domain can't be a CNAME. more: networking.

shared drive

$ ssh dashboard@ironwire.sh drive create 10G
created drive: 10 GiB
attach it with `drive attach <machine>` or `create <name> --drive`

`drive [create <size> | resize <size> | attach <machine> | detach <machine> | delete]`

manage your account's shared drive (one per account; mounts at /mnt/share on attached machines).

drive: show the drive's size and where it's attached; without one: no drive — create one with `drive create <size>`.
drive create [<size>]: create the drive; the size is optional and defaults to the platform default. already have one: drive already exists (use resize).
drive resize <size>: grow the drive; it can never shrink: drive is grow-only: cannot shrink <cur> → <new> MiB.
drive attach <machine> / drive detach <machine>: mount or unmount it on a machine; takes effect on the machine's next boot.
drive delete: detach everywhere and delete the drive.

more: shared drive.

environment variables

$ ssh dashboard@ironwire.sh env set API_KEY sk-123 --machine=web
set API_KEY — restart the machine to apply

`env [list | set <NAME> <VALUE> | rm <NAME>] [--machine=<name>]`

manage env vars, account-global by default or scoped to one machine with --machine=. subcommand aliases: ls = list; rm = delete = unset; with no subcommand, list runs.

Flag	Value	Default	Meaning
`--machine=` (or `-m=`)	machine name	account-global	scope the command to one machine's vars.

set is an upsert; everything after the name becomes the value (spaces included). changes apply on the machine's next restart. names starting with IRONWIRE_ are rejected: names starting with IRONWIRE_ are reserved by the control plane. invalid names give invalid variable name "<n>" (use letters, digits, and underscore; must not start with a digit).

JSON: env list → {"ok":true,"env":[{"name","value"}]}. more: environment variables.

account

$ ssh dashboard@ironwire.sh usage
2/5 machines · 3 vCPU in use (max 4/machine) · 3/16 GiB · 20/100 GiB disk

`whoami`

show your handle: you are <handle>. JSON: {"ok":true,"handle":…,"admin":…,"machine":…}. more: getting started.

`usage`

show your usage against your budget: machines, vCPU (a per-machine ceiling, not a summed total), memory, and disk. JSON: {"ok":true,"usage":{…},"budget":{…},"vcpu_max_per_machine":…}. more: quotas.

`keys`

list your SSH keys: fingerprint, label, and the date each was added. more: connecting.

`link`

get a short-lived code to add another device: on the new machine, run ssh dashboard@ironwire.sh, choose "link a device", and enter the code. more: connecting.

`unlink <fingerprint-prefix>`

remove one of your SSH keys by fingerprint prefix. an ambiguous prefix gives ambiguous prefix "<prefix>" (matches <n> keys), and you can never remove your last key: cannot remove your only key. more: connecting.

`help`

aliases: -h, --help

print the built-in command summary. running with no command at all prints the same text.