tritonctl instance

tritonctl instance manages instances. tritonctl disk manages the disks that belong to an instance, so both families are documented here.

Synopsis

tritonctl instance list [--image <IMAGE>] [--state <STATE>]
tritonctl instance show <INSTANCE>
tritonctl instance create --name <NAME> --image <IMAGE> --subnet <SUBNET> (--package <PACKAGE> | --cpu <CPU> --memory <SIZE>) [OPTIONS]
tritonctl instance start <INSTANCE> [--wait]
tritonctl instance stop <INSTANCE> [--wait]
tritonctl instance reboot <INSTANCE> [--wait]
tritonctl instance delete <INSTANCE> [--force] [--wait] [-y] [-n] [--keep-going]
tritonctl instance nics <INSTANCE>
tritonctl instance disks <INSTANCE>
tritonctl instance tags <INSTANCE> [--set <KEY=VALUE>]... [--unset <KEY>]... [--replace]
tritonctl instance logs <INSTANCE> [--source <SOURCE>] [--lines <N>]

tritonctl disk list --instance <INSTANCE>
tritonctl disk show <DISK> [--instance <INSTANCE>]
tritonctl disk resize <DISK> --size <SIZE> [--instance <INSTANCE>]

instance also answers to inst. instance list and disk list also answer to ls, and instance delete also answers to rm.

Six instance subcommands have top-level shortcuts that take the same arguments:

Shortcut	Runs
tritonctl ls	tritonctl instance list
tritonctl create	tritonctl instance create
tritonctl delete, tritonctl rm	tritonctl instance delete
tritonctl start	tritonctl instance start
tritonctl stop	tritonctl instance stop
tritonctl reboot	tritonctl instance reboot

Common behavior

The global flags, output formats, and confirmation flags are described in the tritonctl command index. Four of them matter on this page:

Topic	Effect on this command family
Project	instance list and instance create need a project. Finding an instance by name or prefix also needs one.
Resource references	<INSTANCE>, --image, --subnet, --ssh-key, --package, and <DISK> accept a name, a full UUID, or a UUID prefix. --image and --package also accept name@version. --ssh-key also accepts a fingerprint.
Output formats	Lists print a table; show and every command that prints one record print key value lines. -j prints the raw JSON.
Confirmation	instance delete prints a plan and asks before it acts.

Without a project, a command that needs one fails before it sends a request. For instance create:

creating an instance needs a project; pass --project, or set one with `tritonctl configure --project`

A name or prefix for an instance without a project fails with:

finding an instance by name needs a project; pass --project, or set one with `tritonctl configure --project`

A full UUID is read directly and needs no project.

The --wait flag

create, start, stop, reboot, and delete accept --wait. Without it, create, start, stop, and reboot print the record the server answered with and exit while the change is still in progress. delete prints no record.

The rest of this section covers create, start, stop, and reboot. delete --wait is described at the end.

With --wait, the command reads the instance every 2 seconds until it reaches the target state, then prints the record. Each state change prints one line on stderr:

waiting for <NAME>: <STATE>

Subcommand	Waits until
create, start, reboot	running
stop	stopped

For create, start, reboot, and stop, an instance that reaches failed ends the wait with an error:

instance <NAME> failed: <REASON>

The wait gives up after 15 minutes:

instance <NAME> is still <STATE> after 15m; check it later with `tritonctl instance show <NAME>`

When --wait is set on these four commands and the global --timeout is shorter than 15 minutes, the request timeout is raised to 15 minutes for that command.

delete --wait is different. It prints waiting for <NAME> to be deleted, polls until the instance reads as 404, then prints <NAME> is gone. It does not stop on failed, prints no record, and keeps the request timeout. After 15 minutes it fails with:

instance <NAME> still exists after 15m; check it later with `tritonctl instance show <NAME>`

tritonctl instance list

Synopsis

tritonctl instance list [--image <IMAGE>] [--state <STATE>]

Description

Lists the instances in the project. Calls GET /v1/instances with project=, plus image= and state= when given. Sandbox instances are not listed.

The command needs a project. --image does not replace it. Without a project:

listing instances needs a project; pass --project, or set one with `tritonctl configure --project`

Options

Flag	Value	Default	Description
--image <IMAGE>	Name, name@version, UUID, or prefix	None	Only instances booted from this image. The CLI resolves the reference to a UUID first.
--state <STATE>	pending, provisioning, running, stopping, stopped, deleting, failed	None	Only instances in this state. Matched case-sensitively; any other value is a usage error.

Output

Column set	Columns
Default	SHORTID, NAME, IMG, STATE, FLAGS, AGE
-l	ID, NAME, IMG, BRAND, CPU, MEMORY, STATE, CREATED_AT

Rows are sorted by created_at.

Column	Content
SHORTID	First 8 characters of the instance UUID.
IMG	First 8 characters of the image UUID.
STATE	The bare state name, for example running. A failed instance prints failed (<REASON>).
FLAGS	B for a bhyve instance, K for kvm, L for lx. A native zone prints -.
AGE	Time since creation, in one unit, for example 5h.
MEMORY	Memory in human-readable units.

tritonctl instance show

Synopsis

tritonctl instance show <INSTANCE>

Description

Reads one instance. Calls GET /v1/instances/{instance_id}. An instance in another tenant returns 404, the same response as an instance that does not exist.

Arguments

Argument	Value	Required	Description
<INSTANCE>	Name, UUID, or prefix	Yes	Instance to read.

Output

The command prints every top-level field of the instance record as one key value line, under its JSON name. A nested object prints one line per member as parent.child, so the state prints as state.state, and a failed instance adds state.reason:

state.state   failed
state.reason  <REASON>

-o selects lines by key, for example -o name,state.state.

The record carries id, name, description, image_id, primary_subnet_id, ssh_key_ids, cpu, memory_bytes, brand, cpu_class, disk_class, provenance, state, tenant_id, project_id, created_at, and updated_at. host_cn_uuid, billing_id, time_state_updated, and tags appear only when set.

In -j output the state is an object, keyed state:

"state": { "state": "failed", "reason": "<REASON>" }

tritonctl instance create

Synopsis

tritonctl instance create --name <NAME> --image <IMAGE> --subnet <SUBNET> (--package <PACKAGE> | --cpu <CPU> --memory <SIZE>) [OPTIONS]

Description

Creates an instance in the project. Calls POST /v1/instances?tenant=<TENANT_UUID>&project=<PROJECT_UUID>. The CLI reads the tenant from /v1/me and resolves the image, subnet, SSH keys, and package to UUIDs before it sends the request.

The server answers 201 as soon as it has written the instance record in pending. Placement, the provision job, and the wait for the compute node run afterwards in the instance-create saga, and the outcome lands on the record: running, or failed with a reason. Without --wait, the command prints the pending record.

If the server cannot start the saga, it marks the instance failed with the reason Provisioning could not be started. and answers 500. The record stays so you can read and delete it.

Options

Flag	Value	Default	Description
--name <NAME>	String	Required	Instance name. 1 to 63 bytes. No / or \, no ASCII control bytes, no leading or trailing whitespace. Unique within the project.
--description <DESCRIPTION>	String	Empty	Free-text description.
--image <IMAGE>	Name, name@version, UUID, or prefix	Required	Image to boot. A name is looked up among the public images and, with a project, your silo's, tenant's, and project's images.
--subnet <SUBNET>	Name, UUID, or prefix	Required	Subnet for the primary NIC. A name is looked up across every VPC of the project.
--ssh-key <KEY>	Name, fingerprint, UUID, or prefix	None	SSH key to install. Repeatable. Looked up among your own keys.
--package <PACKAGE>	Name, name@version, UUID, or prefix	None	Size the instance from a package in your silo's catalog. A bare name is the current version. Conflicts with --cpu and --memory. The package's default disks apply unless a --disk names its own.
--cpu <CPU>	Integer	None	Virtual CPUs. Needed without --package.
--memory <SIZE>	Size	None	Memory. Needed without --package.
--disk <SPEC>	Disk spec	None	A disk. Repeatable. See Disk specs.
--data-disk <SIZE[,replicas=N][,tier=T]>	Disk spec	None	A replicated data disk. The server accepts at most one. The same as --disk size=<SIZE>,type=replicated,.... The server refuses replicas= and tier= from a tenant; the silo's storage class decides both, so give the size alone.
--tag <KEY=VALUE>	Key and value	None	A tag. Repeatable. The value may be empty and may contain =; the key may not be empty.
--user-data <FILE>	Path, or -	None	cloud-init user data, read from the file, or from stdin for -.
--wait	Flag	Off	Wait until the instance is running. See The --wait flag.

A size is a number of bytes, or a number with K, M, G, T, or P. Every unit is binary: 4G and 4GB both mean 4 GiB. A fraction such as 1.5G is accepted with a unit.

Without --package, both --cpu and --memory are required. Without them the command fails before it sends a request:

size the instance with --package, or with both --cpu and --memory

The CLI sends cpu_class and disk_class as generic. It has no flag for an extra NIC, a pinned MAC address, or placement traits.

Disk specs

A --disk value is a comma-separated list. Its first part decides the role:

Form	Disk
50G	A bare size first sizes the local boot disk.
boot[,size=<SIZE>][,type=local|replicated][,class=<CLASS>]	The boot disk.
size=<SIZE>,type=replicated[,class=<CLASS>]	A replicated data disk. A data disk needs size=.

Part	Values
size=	A size, as above.
type=	local or replicated. Default local.
class=	local, replicated_standard, or replicated_performance. Sets the type; a type= that disagrees is refused.
replicas=	A number. Implies type=replicated.
tier=	performance or standard. Implies type=replicated.

The CLI refuses more than one boot entry with give one boot --disk, and replicas or tier on a local disk with replicas and tier are for type=replicated.

The server applies further rules:

• Your silo's storage class sets the copies and tier of a replicated disk. A tenant request that names replicas= or tier= is refused with disks: disk <N>: choose a storage_class; the silo sets replicas and tier. Use class= instead.
• A class the silo does not offer is refused with disks: disk <N>: this silo does not offer <CLASS> storage.
• A local data disk is refused with disks: disk <N>: local data disks are not available yet.
• An instance has at most one data disk. A second is refused with an instance may have at most 1 data disks.
• A replicated boot disk and a data disk together are refused with an instance with a replicated boot disk cannot have data disks yet.
• Without a boot disk spec, a silo that offers no local storage refuses the create with disks: the boot disk: this silo does not offer local storage.
• A replicated boot disk needs a bhyve image that can be imported. Otherwise the create is refused with This image cannot use a replicated boot disk. Create the instance without one, or choose another image.

How the boot disk is sized

With --package, the package supplies the boot disk size, and giving a boot size with --disk as well returns 400. Without a package and with no boot size given, the server sizes the boot disk from the image's content size. For an image whose compatibility block names the bhyve brand, the floor is 20 GiB.

A boot size given with --disk must be at least the image's content size and at most 16 TiB. Under --package, the package's disk size must hold the image.

Server-side validation

Condition	Response
--cpu 0	400, cpu must be greater than zero
--memory 0	400, memory_bytes must be greater than zero
Boot size 0 or above 16 TiB	400, disk_bytes must be greater than zero and at most 16 TiB
Boot size below the image's content size	400, The boot disk must be at least <BYTES> bytes to hold the image.
Package disk smaller than the image	400, image needs <BYTES> bytes of boot disk but the package sells <BYTES>; choose a package with a larger disk or a smaller image
User data the metadata rules refuse	400, user_data: followed by the reason
Free-form shape outside the silo's limits	400, naming the limit
Silo allows packages only, and no --package	403, free-form instance sizing is disabled by this silo's provisioning policy; select an available package
Silo allows free-form only, and --package set	403, package-based instance sizing is disabled by this silo's provisioning policy; supply explicit dimensions
Project quota exceeded	403
Image, SSH key, subnet, or project not visible to you, or a subnet outside the project	404
Image that cannot receive SSH keys or a password	409, This image cannot receive SSH keys or a password, so you could not sign in. Choose another image, or ask your administrator to import one that can.
Name taken in the project	409, instance with name "<NAME>" already exists in project <PROJECT_UUID>
Name breaks the name rules	409, naming the field
Replicated disks requested and too few storage nodes	400, Replicated disks are not available here right now. Use local disks, or ask your administrator.

Placement runs after the 201, so a capacity shortage does not reach the create response. The instance moves to failed with the reason No compute node has room for this instance right now. Try again later or choose a smaller package. Any other provisioning failure without a more specific reason reads Provisioning did not complete.

Output

The instance record, in the same form as tritonctl instance show. Without --wait, state.state is pending.

tritonctl instance start

Synopsis

tritonctl instance start <INSTANCE> [--wait]

Description

Starts a stopped instance. Calls POST /v1/instances/{instance_id}/start. The server runs the instance-lifecycle saga, moves the record to pending, and answers 202.

Accepted only from stopped. Any other state returns 409:

instance <INSTANCE_UUID> is in <STATE>; expected one of [Stopped]

Arguments and options

Argument or flag	Value	Default	Description
<INSTANCE>	Name, UUID, or prefix	Required	Instance to start.
--wait	Flag	Off	Wait until the instance is running.

Output

The instance record, in the same form as tritonctl instance show.

tritonctl instance stop

Synopsis

tritonctl instance stop <INSTANCE> [--wait]

Description

Stops a running instance. Calls POST /v1/instances/{instance_id}/stop. The server moves the record to stopping and answers 202.

Accepted only from running. Any other state returns 409. An instance with an active migration returns 409; the same holds for start and reboot.

Arguments and options

Argument or flag	Value	Default	Description
<INSTANCE>	Name, UUID, or prefix	Required	Instance to stop.
--wait	Flag	Off	Wait until the instance is stopped.

Output

The instance record, in the same form as tritonctl instance show.

tritonctl instance reboot

Synopsis

tritonctl instance reboot <INSTANCE> [--wait]

Description

Reboots a running instance. The CLI verb is reboot; the route it calls is POST /v1/instances/{instance_id}/restart. The server moves the record to stopping and answers 202. A successful restart goes from stopping straight back to running.

Accepted only from running. Any other state returns 409.

Arguments and options

Argument or flag	Value	Default	Description
<INSTANCE>	Name, UUID, or prefix	Required	Instance to reboot.
--wait	Flag	Off	Wait until the instance is running again.

Output

The instance record, in the same form as tritonctl instance show.

tritonctl instance delete

Synopsis

tritonctl instance delete <INSTANCE> [--force] [--wait] [-y] [-n] [--keep-going]

Description

Deletes an instance and releases its NIC, IP, and disk records. Calls DELETE /v1/instances/{instance_id} with a force= query parameter.

The command prints its plan on stderr and asks before it sends the request:

This will make the following changes:
    delete instance <NAME> (<SHORTID>), state <STATE>
Would you like to continue? [y/N]

-y answers yes; -n prints the plan and stops. With no terminal and no -y, the command fails. See Confirmation.

The server moves the record to deleting and answers 202. The instance-delete saga then detaches floating IPs, tears down the instance on its compute node, and releases the record. Reads answer 404 once it is gone.

danger

Deleting an instance destroys it and its disks. There is no undo.

Without --force, the instance must be stopped or failed. Any other state returns 409:

instance <INSTANCE_UUID> is in <STATE>; expected one of [Stopped, Failed]

An instance with an active migration returns 409.

Arguments and options

Argument or flag	Value	Default	Description
<INSTANCE>	Name, UUID, or prefix	Required	Instance to delete.
--force	Flag	Off	Delete from any state except deleting, and do not wait for the compute node to confirm the teardown. Fleet operators only.
--wait	Flag	Off	Wait until the instance reads as 404.
-y, --yes	Flag	Off	Answer yes to the confirmation.
-n, --dry-run	Flag	Off	Print the plan and stop.
--keep-going	Flag	Off	Keep executing after a step fails.

--force from any principal that is not a fleet operator returns 403:

force delete is operator-only

Output

Nothing on stdout in table mode. The plan, the step line, and Completed successfully (elapsed <TIME>). go to stderr. With -j, stdout carries the plan as JSON.

tritonctl instance nics

Synopsis

tritonctl instance nics <INSTANCE>

Description

Lists the instance's network interfaces. Calls GET /v1/instances/{instance_id}/nics.

Output

Column set	Columns
Default	SHORTID, NAME, MAC, IP, INSTANCE, AGE
-l	ID, NAME, MAC, IP, IP6, INSTANCE_ID, SUBNET_ID, VPC_ID, CREATED_AT

IP is the NIC's primary IPv4 address and IP6 its primary IPv6 address. An absent address prints -.

tritonctl instance disks

Synopsis

tritonctl instance disks <INSTANCE>

Description

Lists the instance's disks. Calls GET /v1/disks?instance=<INSTANCE_UUID>, the same request as tritonctl disk list, and prints the same columns.

tritonctl instance tags

Synopsis

tritonctl instance tags <INSTANCE> [--set <KEY=VALUE>]... [--unset <KEY>]... [--replace]

Description

With no flag, prints the instance's tags as key value lines. With -j, prints them as a JSON object.

With any flag, the command computes the new tag set and sends it with PUT /v1/instances/{instance_id}/tags, which replaces every tag on the instance. The starting set is the current tags, or an empty set with --replace. --set entries are applied, then --unset entries. The command prints the resulting tags.

Tags are firewall rule targets, so a change re-applies the VPC's firewall rules.

Options

Flag	Value	Default	Description
--set <KEY=VALUE>	Key and value	None	Set a tag. Repeatable. The value may be empty.
--unset <KEY>	Key	None	Remove a tag. Repeatable.
--replace	Flag	Off	Remove every tag not set by --set in this command.

A --set value without =, or with an empty key, is a usage error: "<VALUE>" is not key=value.

tritonctl instance logs

Synopsis

tritonctl instance logs <INSTANCE> [--source <SOURCE>] [--lines <N>]

Description

Prints the last lines of one of the instance's logs, one line per entry. Calls GET /v1/tenants/{tenant_id}/projects/{project_id}/instances/{instance_id}/logs/{source}.

When the server no longer holds lines older than the ones returned, the command prints on stderr:

older lines were dropped; --lines reaches only what is still held

Options

Flag	Value	Default	Description
--source <SOURCE>	console or platform	console	console is the guest's console log. Any other value returns 400.
--lines <N>	Integer	100	How many lines from the end.

tritonctl disk list

Synopsis

tritonctl disk list --instance <INSTANCE>

Description

Lists the disks attached to one instance. Calls GET /v1/disks?instance=<INSTANCE_UUID>.

Options

Flag	Value	Default	Description
--instance <INSTANCE>	Name, UUID, or prefix	Required	Instance whose disks to list.

Output

Column set	Columns
Default	SHORTID, NAME, INSTANCE, KIND, CLASS, SIZE, AGE
-l	ID, NAME, INSTANCE, KIND, CLASS, COPIES, SIZE_BYTES, SOURCE_IMAGE, CREATED_AT

Rows are sorted by name. KIND is boot or data. CLASS is local, replicated_standard, or replicated_performance. SIZE is human-readable; SIZE_BYTES is exact.

tritonctl disk show

Synopsis

tritonctl disk show <DISK> [--instance <INSTANCE>]

Description

Reads one disk. Calls GET /v1/disks/{disk_id}.

A disk name or prefix is looked up among one instance's disks, so it needs --instance. Without it:

finding a disk by name needs its instance; pass --instance, or the disk's uuid

A full UUID with an --instance that does not own the disk fails with disk <DISK_UUID> is not on instance <SHORTID>.

Arguments and options

Argument or flag	Value	Default	Description
<DISK>	Name, UUID, or prefix	Required	Disk to read.
--instance <INSTANCE>	Name, UUID, or prefix	None	The disk's instance. Needed to find a disk by name.

Output

Every field of the disk record as key value lines: id, name, description, instance_id, kind, storage_class, size_bytes, tenant_id, project_id, and created_at, plus copies and source_image_id when set.

tritonctl disk resize

Synopsis

tritonctl disk resize <DISK> --size <SIZE> [--instance <INSTANCE>]

Description

Grows a disk's backing volume. Calls POST /v1/disks/{disk_id}/resize. The server grows the disk record, enqueues a ResizeDisk job for the compute node, and answers 202.

The operation is grow-only. --size is the new total size, not a delta. A value at or below the current size returns 409:

disk resize must grow: requested <SIZE_BYTES> <= current <CURRENT_SIZE_BYTES>

A running guest sees the new capacity after a reboot.

Arguments and options

Argument or flag	Value	Default	Description
<DISK>	Name, UUID, or prefix	Required	Disk to grow.
--size <SIZE>	Size, for example 50G	Required	New total size. Must be larger than the current size and at most 16 TiB.
--instance <INSTANCE>	Name, UUID, or prefix	None	The disk's instance. Needed to find a disk by name.

Server-side preconditions

Condition	Response
Disk not on a local volume, such as a replicated disk	400, this disk cannot be resized yet
--size 0 or above 16 TiB	400, size_bytes must be greater than zero and at most 16 TiB
Parent instance not yet placed on a compute node	400, instance is not placed on a CN yet
Parent instance not running or stopped	400, instance must be running or stopped to resize its disk
--size at or below the current size	409

Output

The resized disk record as key value lines, in the same form as tritonctl disk show. A second line on stderr depends on the parent instance's state:

Parent state	stderr
running	reboot the instance to see the new capacity
stopped	the larger disk is available on the next start

With -j, stdout carries the whole response: the disk record and the reboot_required boolean.

Lifecycle states

An instance is in exactly one of these states.

State	Meaning
pending	Created or start requested, not yet claimed by a compute node agent.
provisioning	An agent has claimed the provisioning job and is working.
running	Up and running.
stopping	Stop or reboot requested; the agent is winding down.
stopped	Fully stopped.
deleting	Delete accepted. The instance goes away once the platform releases it.
failed	Unrecoverable error. Carries a reason. The instance must be deleted.

Accepted transitions:

Subcommand	Accepted from	Server answers	Instance moves to
instance create	None	201	pending
instance start	stopped	202	pending
instance stop	running	202	stopping
instance reboot	running	202	stopping
instance delete	stopped, failed	202	deleting

See also

• tritonctl command index
• tritonctl networking reference
• Create an instance
• Run your first instance
• How instance disks work