tritonctl command index

tritonctl is the tenant command line client for Triton Cloud. It calls the customer surface of tritond and never targets the operator /v1/system/* endpoints, which belong to tritonadm.

Your tenant comes from the bearer token you authenticate with. tritonctl never sends a tenant= selector of its own. The global --project flag narrows a request to one project inside that tenant.

Every resource is addressed by UUID. No tritonctl argument accepts a resource name.

Command index

tritonctl has seventeen top-level commands.

Command	Subcommands	Purpose
configure	None	Authenticate against an endpoint and write the endpoint plus token pair to the config file.
login	None	Re-authenticate against the configured endpoint and rewrite the stored tokens.
logout	None	Delete the config file, including the stored credentials.
whoami	None	Print the resolved endpoint and the identity behind the current credential.
env	None	Print shell export lines for the resolved endpoint and access token.
instance	list, show, create, delete, start, stop, reboot	Manage instances.
disk	list, show, resize	List and show the disks of an instance, and grow a disk.
vpc	list, show, create, delete	Manage VPCs.
subnet	list, show, create, delete	Manage subnets inside a VPC.
floating-ip	list, show, create, delete, attach, detach	Allocate floating IPs and bind them to a NIC.
firewall-rule	list, show, create, delete	Manage firewall rules on a VPC.
nat-gateway	list, show, create, delete	Manage NAT gateways on a VPC.
route-table	list, show, create, delete	Manage route tables inside a VPC.
route	list, show, create, delete	Manage routes inside a route table.
image	list, show	Read the image catalog.
ssh-key	list, show, create, delete	Manage the SSH keys owned by your user.
meta	list, get, set, unset, realized	Read and write project and instance metadata.

There is no console, ssh, project, tenant, user, snapshot, or migration command in tritonctl.

Global flags

All of these are declared global, so they are accepted before or after a subcommand.

Flag	Value	Behavior
--endpoint	URL	Cluster endpoint. Falls back to TRITONCTL_ENDPOINT, then the config file.
--api-key	Token string	Bearer credential to send. Falls back to TRITONCTL_API_KEY.
--project	UUID	Project to scope tenant resources to. Reads TRITONCTL_PROJECT when the flag is absent.
-o, --output	table, wide, json, yaml	Output format. See Output formats.
--no-headers	Flag	Omit the table header row. Table output only.
-h, --help	Flag	Print help.
-V, --version	Flag	Print the version.

Output formats

-o accepts four values. When you do not pass -o, tritonctl selects table if stdout is a terminal and json when stdout is piped or redirected.

Value	Rendering
table	Borderless column layout with a header row, unless --no-headers is set.
wide	Accepted by the flag. No tritonctl subcommand adds columns for it, so it renders the same columns as table.
json	Pretty-printed JSON of the full server record.
yaml	YAML of the full server record.

JSON is the stable interface. Table column layout is human-facing and carries no stability guarantee.

Enums are rendered through their serde wire form rather than a Rust debug name. LifecycleState is an adjacently tagged enum, so the STATE column of tritonctl instance list and the lifecycle: line of tritonctl instance show render a JSON object, not a bare string:

{"state":"running"}

Configuration file

tritonctl keeps one endpoint and, when you are logged in, one token pair in a single JSON file. The file holds an endpoint string and an optional tokens object with access_token, refresh_token, access_expires_at, and refresh_expires_at.

The path is the platform user configuration directory joined with triton/tritonctl/config.json. The source documents this as ~/.config/triton/tritonctl/config.json. tritonctl configure prints the resolved path after writing.

On Unix the file is created with mode 0600 and moved into place with an atomic rename, so the token bytes never sit on disk world-readable.

There are no named profiles. One config file holds exactly one endpoint and one token pair. To work against a second cluster, pass --endpoint, set TRITONCTL_ENDPOINT, or point TRITONCTL_CONFIG_DIR at a different directory.

Environment variables

Variable	Effect
TRITONCTL_ENDPOINT	Endpoint used when --endpoint is absent.
TRITONCTL_API_KEY	Bearer credential used when --api-key is absent.
TRITONCTL_ACCESS_TOKEN	Bearer credential used when no API key is set. Never auto-refreshed.
TRITONCTL_CONFIG_DIR	Replaces the default config directory. The config file becomes $TRITONCTL_CONFIG_DIR/config.json.
TRITONCTL_PROJECT	Default value for --project.
RUST_LOG	tracing filter for diagnostics on stderr. Defaults to warn.

tritonctl env emits TRITONCTL_ENDPOINT and, when a bearer is resolved, TRITONCTL_ACCESS_TOKEN as shell exports, followed by a comment line:

# eval "$(tritonctl env)" to load these into the current shell

Endpoint resolution

tritonctl resolves the endpoint in this order, highest priority first:

1. The --endpoint flag.
2. The TRITONCTL_ENDPOINT environment variable.
3. The endpoint field in the config file.

With none of the three, the command fails with:

no endpoint configured: pass --endpoint, set TRITONCTL_ENDPOINT, or run `tritonctl configure`

Credential resolution

tritonctl resolves the bearer credential in this order, highest priority first:

1. The --api-key flag.
2. The TRITONCTL_API_KEY environment variable.
3. The TRITONCTL_ACCESS_TOKEN environment variable. This value is sent as-is and is never refreshed.
4. The token pair in the config file.

The first three short-circuit the stored-token path entirely. When none is present, tritonctl sends no Authorization header.

A resolved bearer is attached as Authorization: Bearer on every request. The HTTPS client bundles the Mozilla webpki-roots trust store instead of reading a system CA bundle, because the illumos global zone ships none.

Token refresh

When the credential comes from the config file, tritonctl inspects access_expires_at before each command. Inside 60 seconds of expiry it POSTs the refresh token to /v1/auth/refresh, writes the new pair back to the config file, and uses the new access token for the command. Outside that window it uses the stored access token unchanged.

If the refresh token has itself expired, the command fails with:

refresh token has expired; run `tritonctl login` to re-authenticate

configure and login both obtain a pair by POSTing a username and password to /v1/auth/login on the resolved endpoint. When --username is omitted, both prompt for it. The password is read from stdin with --password-stdin and prompted for otherwise. configure additionally prompts for the endpoint, with http://localhost:8080 as the default value.

Identity output

tritonctl whoami prints the resolved endpoint, then one identity line. For a bearer that parses as a three-part JWT it prints identityd token followed by whichever of the claims sub, tenant_id, realm_scope, scope, and exp are present. The payload is base64-decoded for display only, with no signature verification. For any other bearer it prints API key.

With no credential resolved, the identity line is:

auth:     not authenticated (run `tritonctl login`)

Scope requirements

Some commands need a selector that the flag definitions do not force. The server rejects the request when the selector is missing.

Command	Requirement
instance list	Needs --project or --image. Unscoped, the server returns 400 MissingScope.
instance create	The server requires both tenant= and project=. tritonctl sends project= only, so this returns 400 MissingScope.
instance delete --force	The server restricts force delete to fleet operators and returns 403 Forbidden otherwise. Non-forced delete requires the instance to be stopped or failed.
disk list	--instance is required by both the CLI and the server.
vpc list, vpc create	The server requires both tenant= and project=. tritonctl sends project= only, so these return 400 MissingScope.
subnet list, subnet create	--vpc is required by both the CLI and the server.
floating-ip list, floating-ip create	The server requires both tenant= and project=. tritonctl sends project= only, so these return 400 MissingScope.
firewall-rule list	--vpc is optional in the CLI. The server requires vpc=.
nat-gateway list	--vpc is optional in the CLI. The server requires vpc=.
route-table list	--vpc is optional in the CLI. The server requires vpc=.
route list	--route-table is optional in the CLI. The server requires route_table=.
image list	tritonctl sends scope=tenant. The server implements scope=public only and returns 400 ScopeNotImplemented.

warning

instance create, vpc list, vpc create, floating-ip list, floating-ip create, and image list cannot complete against the current server for the reasons in the table above. instance show, image show, and the per-VPC network commands are unaffected.

See also

• tritonctl instance reference
• tritonctl networking reference
• Create an instance
• Networking concepts