tritonctl instance
tritonctl instance manages instances. tritonctl disk manages the disks that
belong to an instance, so both families are documented here.
The tenant is taken from the bearer token. tritonctl never sends a tenant=
selector. The global --project flag supplies the project= selector where a
command uses one.
Every identifier argument is a UUID. No argument accepts a resource name.
Synopsis
tritonctl [GLOBAL FLAGS] instance list [--image <IMAGE>] [--state <STATE>]
tritonctl [GLOBAL FLAGS] instance show <ID>
tritonctl [GLOBAL FLAGS] instance create --name <NAME> --image-id <IMAGE_ID> --primary-subnet-id <PRIMARY_SUBNET_ID> --cpu <CPU> --memory-bytes <MEMORY_BYTES> [OPTIONS]
tritonctl [GLOBAL FLAGS] instance start <ID>
tritonctl [GLOBAL FLAGS] instance stop <ID>
tritonctl [GLOBAL FLAGS] instance reboot <ID>
tritonctl [GLOBAL FLAGS] instance delete <ID> [--force]
tritonctl [GLOBAL FLAGS] disk list --instance <INSTANCE>
tritonctl [GLOBAL FLAGS] disk show <ID>
tritonctl [GLOBAL FLAGS] disk resize <ID> --size-bytes <SIZE_BYTES>
There are seven instance subcommands and three disk subcommands. There is no
console, ssh, snapshot, migrate, attach, or detach subcommand in
either family.
Global flags
--endpoint, --api-key, --project, -o/--output, and --no-headers are
declared global and are accepted before or after any subcommand on this page.
Their resolution order is documented in the
tritonctl command index.
Two of them change what these commands do:
| Flag | Effect on this command family |
|---|---|
--project <PROJECT> | Supplies the project= selector on instance list and instance create. Read from TRITONCTL_PROJECT when the flag is absent. Ignored by the other subcommands on this page. |
-o, --output <OUTPUT> | table, wide, json, or yaml. Defaults to table when stdout is a terminal and json otherwise. No subcommand on this page defines extra wide columns, so wide renders the same columns as table. |
tritonctl instance list
Synopsis
tritonctl instance list [--image <IMAGE>] [--state <STATE>]
Description
Lists instances. Calls GET /v1/instances.
The command sends project= from the global --project, image= from
--image, and state= from --state. The server dispatches on the narrowest
selector it is given, preferring image= over project=.
The server requires at least one scoping selector. With neither --project nor
--image, the request returns 400 MissingScope:
set `image=`, `cn=`, or `tenant=&project=` to scope the list
--state is matched case-insensitively against the lifecycle state names in
Lifecycle states.
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--image <IMAGE> | UUID | None | Restrict to instances whose boot image matches. |
--state <STATE> | String | None | Restrict to one lifecycle state. |
Output
Table output has four columns.
ID NAME STATE IMAGE
STATE renders the serde wire form of the LifecycleState enum, which is
adjacently tagged, so the cell contains a JSON object rather than a bare state
name. -o json returns the full paginated envelope, an items array plus an
optional next_page cursor. tritonctl sends no page token and reads only
items.
tritonctl instance show
Synopsis
tritonctl instance show <ID>
Description
Reads one instance. Calls GET /v1/instances/{instance_id}.
The server resolves the instance, then authorizes against the instance's own
tenant. An instance in another tenant returns 404, the same response as an
instance that does not exist.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
<ID> | UUID | Yes | Instance to read. |
Output
Table output prints four labeled lines and a trailing note:
id: <INSTANCE_UUID>
name: <INSTANCE_NAME>
lifecycle: <LIFECYCLE_STATE>
image: <IMAGE_UUID>
(use -o json for the full record)
-o json returns the whole Instance record, including brand, cpu,
memory_bytes, primary_subnet_id, ssh_key_ids, host_cn_uuid, tenant_id,
project_id, created_at, and updated_at.
tritonctl instance create
Synopsis
tritonctl instance create --name <NAME> --image-id <IMAGE_ID> --primary-subnet-id <PRIMARY_SUBNET_ID> --cpu <CPU> --memory-bytes <MEMORY_BYTES> [--description <DESCRIPTION>] [--ssh-key-id <SSH_KEY_IDS>] [--disk-bytes <DISK_BYTES>]
Description
Creates an instance. Calls POST /v1/instances with project= from the global
--project. Without --project the command fails before sending a request:
--project is required to create an instance
The server runs the request through the instance-create saga, which allocates
the NIC, IP, and boot disk, runs placement, and enqueues the provision job.
POST /v1/instances requires both the tenant= and project= selectors.
tritonctl sends project= only, so this command returns 400 MissingScope
against the current server:
POST /v1/instances requires `?tenant=<uuid>&project=<uuid>` selectors
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--name <NAME> | String | None. Required. | Instance name. |
--description <DESCRIPTION> | String | None | Free-text description. |
--image-id <IMAGE_ID> | UUID | None. Required. | Boot image. The principal must be able to see it, or the server returns 404. |
--primary-subnet-id <PRIMARY_SUBNET_ID> | UUID | None. Required. | Subnet the primary NIC attaches to. Must live in a VPC inside the same project. |
--ssh-key-id <SSH_KEY_IDS> | UUID, repeatable | Empty | SSH key to inject at first boot. Repeat the flag for more than one key. Each key must live in the same silo as the instance. |
--cpu <CPU> | Integer | None. Required. | vCPU count. The server rejects 0. |
--memory-bytes <MEMORY_BYTES> | Integer | None. Required. | Memory budget in bytes. The server rejects 0. |
--disk-bytes <DISK_BYTES> | Integer | None | Boot disk size in bytes. Omitted, the server sizes the boot disk from the image content size, floored at 20 GiB for bhyve images. The server rejects 0 and any value above 16 TiB. |
The request body also carries extra_nics, mac, and user_data fields, which
the API accepts. tritonctl hardcodes them to empty and null; there are no flags
for them.
Server-side validation
| Condition | Response |
|---|---|
--cpu 0 | 400, cpu must be greater than zero |
--memory-bytes 0 | 400, memory_bytes must be greater than zero |
--disk-bytes 0 or above 16 TiB | 400, disk_bytes must be greater than zero and at most 16 TiB |
| Image or SSH key not visible to the principal | 404 |
Output
On success the command prints the same four labeled lines as
tritonctl instance show.
tritonctl instance start
Synopsis
tritonctl instance start <ID>
Description
Starts a stopped instance. Calls POST /v1/instances/{instance_id}/start, which
runs the instance-lifecycle saga: the record transitions to pending and a
Start job is enqueued for the compute node that hosts the instance.
The transition is accepted only from stopped. An instance with an active
migration returns 409.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
<ID> | UUID | Yes | Instance to start. |
Output
The updated instance record, in the same shape as
tritonctl instance show.
tritonctl instance stop
Synopsis
tritonctl instance stop <ID>
Description
Stops a running instance. Calls POST /v1/instances/{instance_id}/stop. The
record transitions to stopping and a Stop job is enqueued for the host
compute node.
The transition is accepted only from running. An instance with an active
migration returns 409.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
<ID> | UUID | Yes | Instance to stop. |
Output
The updated instance record, in the same shape as
tritonctl instance show.
tritonctl instance reboot
Synopsis
tritonctl instance reboot <ID>
Description
Reboots a running instance. The CLI verb is reboot; the route it calls is
POST /v1/instances/{instance_id}/restart. The record transitions to stopping
and a Restart job is enqueued for the host compute node.
The transition is accepted only from running. An instance with an active
migration returns 409.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
<ID> | UUID | Yes | Instance to reboot. |
Output
The updated instance record, in the same shape as
tritonctl instance show.
tritonctl instance delete
Synopsis
tritonctl instance delete <ID> [--force]
Description
Deletes an instance and releases its NIC, IP, and disk records. Calls
DELETE /v1/instances/{instance_id} with a force= query parameter, which the
command always sends.
The server runs the instance-delete saga: it detaches floating IPs, enqueues
the Delete job for the compute node, waits for a terminal job state, and then
releases the record.
Deleting an instance destroys it and its disks. There is no undo.
Without --force, the instance must be in stopped or failed. Any other state
returns 409:
instance <INSTANCE_UUID> is not deletable in state <STATE>; stop it first
An instance with an active migration returns 409 before any of the above runs.
Arguments and options
| Argument or flag | Type | Default | Description |
|---|---|---|---|
<ID> | UUID | None. Required. | Instance to delete. |
--force | Flag | Off | Skip the terminal-state requirement and do not wait for the compute node to acknowledge the delete. Fleet operators only. |
--force is rejected for any principal that is not a fleet operator:
force delete is operator-only
Output
The command prints one line and ignores --output:
Instance <INSTANCE_UUID> deleted.
tritonctl disk list
Synopsis
tritonctl disk list --instance <INSTANCE>
Description
Lists the disks attached to one instance. Calls GET /v1/disks with the
instance= selector.
--instance is required by both the CLI and the server. The server does not
implement a cross-project disk search.
Options
| Flag | Type | Default | Description |
|---|---|---|---|
--instance <INSTANCE> | UUID | None. Required. | Instance whose disks to list. |
Output
Table output has five columns.
ID NAME INSTANCE KIND SIZE
KIND is boot or data. SIZE is the total size in bytes.
tritonctl disk show
Synopsis
tritonctl disk show <ID>
Description
Reads one disk. Calls GET /v1/disks/{disk_id}. The server derives the owning
tenant from the parent instance and authorizes against it.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
<ID> | UUID | Yes | Disk to read. |
Output
Table output prints five labeled lines and a trailing note:
id: <DISK_UUID>
name: <DISK_NAME>
instance: <INSTANCE_UUID>
kind: <KIND>
size_bytes: <SIZE_BYTES>
(use -o json for the full record)
tritonctl disk resize
Synopsis
tritonctl disk resize <ID> --size-bytes <SIZE_BYTES>
Description
Grows a disk's backing volume. Calls POST /v1/disks/{disk_id}/resize.
The operation is grow-only. --size-bytes is the new total size, not a delta,
and a value at or below the current size returns 409:
disk resize must grow: requested <SIZE_BYTES> <= current <CURRENT_SIZE_BYTES>
The control-plane record and the host volume grow synchronously, and a
ResizeDisk job is enqueued for the host compute node. A running guest reads the
block device size only at boot, so it sees the new capacity after a reboot.
Arguments and options
| Argument or flag | Type | Default | Description |
|---|---|---|---|
<ID> | UUID | None. Required. | Disk to grow. |
--size-bytes <SIZE_BYTES> | Integer | None. Required. | New total size in bytes. Must be greater than the current size and at most 16 TiB. |
Server-side preconditions
| Condition | Response |
|---|---|
--size-bytes 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-bytes at or below the current size | 409 |
Output
Table output is two lines. The second line depends on the reboot_required field
of the response, which is true when the parent instance is running.
Disk <DISK_UUID> resized to <SIZE_BYTES> bytes.
reboot required: the running guest sees the new capacity after a reboot (cloud-init then grows the partition + filesystem)
When the parent instance is stopped:
Disk <DISK_UUID> resized to <SIZE_BYTES> bytes.
the larger disk is available on the next start
Lifecycle states
An instance is in exactly one of these states. --state on
tritonctl instance list is matched case-insensitively against these names.
| State | Meaning |
|---|---|
pending | Created, 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 requested; the agent is winding down. |
stopped | Fully stopped. Safe to delete or start. |
failed | Unrecoverable error. Carries a reason. The instance must be deleted. |
Accepted transitions:
| Subcommand | Accepted from | Instance moves to |
|---|---|---|
instance start | stopped | pending |
instance stop | running | stopping |
instance reboot | running | stopping |
instance delete | stopped, failed | Record released |