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. tritonctl api refuses any path under /v1/system or /internal.

Tenant and project

Your tenant comes from the credential you authenticate with. Some listings need the tenant as a tenant= selector beside the project. For those, tritonctl reads the tenant from /v1/me and keeps it in tenant.json beside the profile's config file. A command that fails with 403 or 404 drops that entry, so the next command reads /v1/me again.

The global --project flag narrows a request to one project inside the tenant. Without the flag, tritonctl uses TRITONCTL_PROJECT, then the project stored by tritonctl configure --project.

These commands need a project and fail without one, among others:

• instance list (and ls), instance create (and create)
• vpc list, vpc create
• floating-ip list, floating-ip create
• external-ip list, external-ip create
• meta with --scope project and no --id
• project show and project quota with no project argument
• subnet list, nat-gateway list, route-table list, route list, and firewall-rule list without their parent flag, which walk every VPC in the project

The error names the action. For instance list:

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

Command index

tritonctl has 42 top-level commands. Every list subcommand except session list also answers to ls, and every delete subcommand answers to rm.

Command	Alias	Subcommands	Purpose
activity	None	None	What happened in your tenant, newest first.
api	None	None	Send one request to the control plane with your session.
api-key	None	create, delete, list	Manage your API keys, for scripts and CI.
completion	None	None	Print a shell completion script for bash, elvish, fish, powershell, or zsh.
configure	None	None	Write settings, and log in only when credentials are given. See Sign-in.
create	None	None	Shortcut for tritonctl instance create.
delete	rm	None	Shortcut for tritonctl instance delete.
disk	None	list, resize, show	Manage disks. See tritonctl instance.
env	None	None	Print shell exports for the current session.
external-ip	None	create, list, release, show, usage	Manage external IPs.
filesystem	fs	attach, attachments, create, delete, detach, list, profiles, resize, show, usage	Shared NFS filesystems.
firewall-rule	fwrule	create, delete, list, show, update	Manage firewall rules. See tritonctl networking.
floating-ip	ip	attach, create, delete, detach, list, show	Manage floating IPs. See tritonctl networking.
image	img	list, show	Browse images.
instance	inst	create, delete, disks, list, logs, nics, reboot, show, start, stop, tags	Manage instances. See tritonctl instance.
llms-full.txt	None	None	Print the agent guide and every flag of every command.
llms.txt	None	None	Print a guide for coding agents and an index of every command. See tritonctl llms.txt.
load-balancer	lb	create, delete, list, show, update	Manage load balancers.
login	None	None	Re-authenticate against the configured endpoint. See Sign-in.
logout	None	None	Delete the config file of the profile in use, including its stored credentials.
ls	None	None	Shortcut for tritonctl instance list.
meta	None	get, list, realized, set, unset	Project and instance metadata.
nat-gateway	None	create, delete, list, show	Manage NAT gateways. See tritonctl networking.
port-forward	None	None	Forward a local port to a port on an instance.
profile	None	create, delete, list, show, use	Manage profiles, one config per cluster or project. See Profiles.
project	None	create, delete, list, quota, show	The projects of your tenant, and their quotas.
reboot	None	None	Shortcut for tritonctl instance reboot.
route	None	create, delete, list, show	Manage routes. See tritonctl networking.
route-table	None	create, delete, list, show	Manage route tables. See tritonctl networking.
sandbox	None	capability, claude, create, delete, exec, exec-attach, fork, fs, git, keepalive, list, network, pause, port-forward, ports, pr, rdp, resize, resume, show, snapshot, ssh-config, start, stop, template, update, url	Agent sandboxes: microVMs that run programs for you. See tritonctl sandbox.
session	None	kill, list	Inspect and end live tunnel sessions.
ssh	None	None	SSH to an instance through the platform relay. Arguments after -- pass to OpenSSH.
ssh-config	None	None	Print an ssh_config block that reaches instances as NAME.triton.
ssh-key	key	create, delete, list, show	Manage SSH keys.
start	None	None	Shortcut for tritonctl instance start.
stop	None	None	Shortcut for tritonctl instance stop.
storage	None	access-keys, buckets, users	Object storage: buckets, storage users, and access keys. See tritonctl storage.
subnet	None	create, delete, list, show, update	Manage subnets. See tritonctl networking.
team	None	invitations, invite, list, remove, revoke, roles	Who is in your tenant, and invitations.
tunnel	None	None	Copy stdin and stdout to a port on an instance. ssh runs this as its ProxyCommand.
vpc	None	create, delete, list, show, update	Manage VPCs. See tritonctl networking.
whoami	None	None	Show the current identity and effective scope. See Identity output.

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	API-key bearer to send. Falls back to TRITONCTL_API_KEY.
--project	Name, UUID, or UUID prefix	Project to work in. Falls back to TRITONCTL_PROJECT, then the stored project.
-p, --profile	Profile name	Profile to use for this command. Falls back to TRITONCTL_PROFILE, then the profile set by profile use.
--timeout	Seconds	Give up on a request after this many seconds. Default 60. 0 waits forever. Does not apply to tritonctl api.
-v, --verbose	Flag	On error, print the full cause chain.
-j, --json	Flag	Emit JSON instead of a table. Same as --format json.
--format	table, json, yaml	Output format. Default table.
-o, --output	Comma-separated columns	Columns to show. A dotted path such as sysinfo.hostname reads a field of the raw record. Table only.
-l, --long	Flag	Show the resource's wider column set. Ignored with -o.
-s, --sort	Comma-separated columns	Sort by these columns. A leading - reverses that column. Applies to tables and JSON.
-H, --no-headers	Flag	Omit the table header row.
--limit	Number	Stop after this many rows.
-h, --help	Flag	Print help.
-V, --version	Flag	Print the version.

Output formats

The table is the default whether stdout is a terminal, a pipe, or a file. Pass -j or --format to get a machine format.

Format	Rendering
table	Column layout with a header row, unless -H is set. A show prints the record as key value lines.
json	Pretty-printed JSON of the raw records.
yaml	YAML of the raw records.

JSON is the stable interface for scripts.

tritonctl refuses flag combinations instead of ignoring a flag:

• -j with --format set to anything other than json.
• -o or -H with -j or --format json|yaml.
• -s, -l, -H, or --limit on a show, which prints one record. -o keeps its meaning on a show and selects which lines print.

The STATE column of tritonctl instance list prints the bare state name, for example running. A failed instance prints failed (<REASON>).

Resource references

Most arguments that name a resource, and --project, accept a name, a full UUID, or a UUID prefix. session kill takes a full UUID only, and a sandbox template reference treats a UUID prefix as a name. tritonctl resolves them in this order:

1. A full UUID is fetched directly.
2. Otherwise, an exact name match wins. A name can look like hex, so a name match beats a prefix match.
3. Otherwise, a UUID prefix of at least four hex characters matches. Hyphens are allowed in the prefix.

Images and packages also match name@version. Some resources match a second field as well: a floating IP or external IP its address, an SSH key its fingerprint, and a NIC its MAC address.

When nothing matches, the command fails with no <NOUN> with name or id "<REF>", followed by the scope searched. When more than one resource matches, the command fails and lists the candidates.

Confirmation

These commands confirm before they act: every delete, external-ip release, filesystem detach, meta unset, sandbox network replace, team remove, team revoke, and api with the DELETE method. Each carries three flags:

Flag	Behavior
-n, --dry-run	Print what would change and stop.
-y, --yes	Answer yes to the confirmation. The summary still prints.
--keep-going	Keep executing after a step fails.

The command prints the plan to stderr, under the line This will make the following changes:. It writes the same plan to plan.json in a per-run directory. That directory is under /var/tritonctl/ when that directory exists and is writable, and otherwise under triton/tritonctl/runs/ in the user state directory, or the local data directory where there is no state directory. It then asks on the terminal:

Would you like to continue? [y/N]

y or yes proceeds. Any other answer prints Aborting. and exits 0. An empty plan prints Nothing to do.. With -j or --format, the plan is the document printed on stdout.

With no terminal to ask on, the command fails unless you pass -y:

Would you like to continue? needs a terminal to answer on; pass -y to confirm

Setting TRITON_CLI_NO_TTY makes tritonctl treat the session as having no terminal. api refuses -n, -y, and --keep-going with any method other than DELETE.

Profiles

A profile is one config file. tritonctl picks the profile in this order:

1. The -p or --profile flag.
2. The TRITONCTL_PROFILE environment variable.
3. The name stored by tritonctl profile use.
4. default.

A profile name is 1 to 64 characters of letters, digits, -, and _.

Profile	Config file
default	<CONFIG_DIR>/config.json
Any other name	<CONFIG_DIR>/profiles/<NAME>/config.json

<CONFIG_DIR> is TRITONCTL_CONFIG_DIR when set. Otherwise it is the platform user configuration directory joined with triton/tritonctl, which the source documents as ~/.config/triton/tritonctl/. profile use writes the chosen name to <CONFIG_DIR>/profile. profile use default removes that file.

profile create <NAME> --endpoint <URL> also accepts --sso-issuer and the global --project. Log in to the new profile with tritonctl -p <NAME> login.

Configuration file

Each config file is JSON with these fields:

Field	Content
endpoint	Cluster endpoint.
tokens	Present when logged in. Holds provider, access_token, refresh_token, access_expires_at, refresh_expires_at, and, for an SSO session, scope.
project	Project UUID used when --project is absent.
project_name	The project's name when it was stored, for display.
sso_issuer	Sign-in service for login --sso.

tokens.provider records which service minted the pair, and therefore where it refreshes. kind is tritond for a password login. It is identityd for an SSO login, with the issuer and the OAuth client_id.

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.

Environment variables

Variable	Effect
TRITONCTL_ENDPOINT	Endpoint used when --endpoint is absent.
TRITONCTL_API_KEY	API-key bearer used when --api-key is absent.
TRITONCTL_ACCESS_TOKEN	Bearer used when no API key is set. Never refreshed.
TRITONCTL_PROJECT	Project used when --project is absent.
TRITONCTL_PROFILE	Profile used when --profile is absent.
TRITONCTL_CONFIG_DIR	Replaces the default config directory.
TRITONCTL_SSO_ISSUER	Sign-in service for login --sso when --issuer is absent.
TRITONCTL_NO_BROWSER	When set, login --sso does not open a local browser.
TRITON_DC_ANCHORS	Path to a PEM file of extra CA certificates to trust. See TLS trust.
TRITON_CLI_NO_TTY	When set, confirmation prompts treat the session as having no terminal.
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 profile's 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 profile's 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.

TLS trust

The HTTPS client builds its trust store from the first source that yields certificates:

1. The system trust store, which honors SSL_CERT_FILE and SSL_CERT_DIR.
2. /opt/local/etc/openssl/certs and other platform certificate paths.
3. The bundled Mozilla roots.

On top of that store, it adds the certificates in the PEM file named by TRITON_DC_ANCHORS. This lets tritonctl verify a control plane certified under a staging or private CA.

Token refresh

When the credential comes from the config file, tritonctl inspects access_expires_at before each command. Inside 60 seconds of expiry it refreshes the pair, 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.

Provider	Refresh target	Error when the refresh token has expired
tritond	POST to /v1/auth/refresh on the endpoint	refresh token has expired; run `tritonctl login` to re-authenticate
identityd	The issuer's token endpoint	session has expired; run `tritonctl login --sso` to re-authenticate

An identityd refresh holds a lock on the config across processes and re-reads the config inside it. It makes up to three attempts on a transport error, a 429, or a 5xx. An OAuth error from the issuer is returned at once.

Sign-in

tritonctl configure runs in one of three ways:

• With only settings flags (--endpoint, --sso-issuer, --project), it writes them without prompting and keeps any stored session. When the endpoint changes and a session exists, it prints a note that the session will now be sent to the new endpoint.
• With --username or --password-stdin, it runs a password login against /v1/auth/login. Without --endpoint or TRITONCTL_ENDPOINT, it prompts for the endpoint, with http://localhost:8080 as the default. It prompts for a missing username or password.
• With --sso, it writes the endpoint and sign-in service, then runs the same browser sign-in as login --sso.

A bare tritonctl configure on a terminal asks whether to sign in through the browser or with a username and password. Off a terminal it runs the password login.

tritonctl login re-authenticates the profile in use. Without --sso it POSTs a username and password to /v1/auth/login. --password-stdin reads the password from stdin. Without that flag, login prompts for it.

tritonctl login --sso runs the OAuth device-authorization flow. It prints a verification URL and a code, opens a local browser when stdout is a terminal, and waits for approval. The URL works from any machine. The sign-in service comes from --issuer, then TRITONCTL_SSO_ISSUER, then sso_issuer in the config. It must be an https:// URL of the form https://<SIGN_IN_HOST>/realms/<REALM>. Plain http:// is accepted only for a literal loopback address. A login that would change the stored sign-in service asks for confirmation on a terminal and is refused without one.

Identity output

tritonctl whoami prints local facts first, then what it learns from the server. It reads the principal from /v1/me and the server version from /v1/health, which needs no credential.

Line	Content
endpoint:	Resolved endpoint.
client:	tritonctl and its version.
credential:	Where the bearer came from: an API key from --api-key or TRITONCTL_API_KEY, an access token from TRITONCTL_ACCESS_TOKEN, or a session token from the config file path, with (sso via <ISSUER>) for an SSO session. With no credential, it prints none and tells you to run tritonctl login.
project:	Project name and UUID, or a note that none is set.
expires:	For a stored session, when the access token expires and how long the refresh token stays valid.
principal:	Username and user UUID, followed by kind:, federated:, tenant:, and silo:. Without a valid session: not available (no valid session).
scope:	For an SSO session, the scope the sign-in service granted. Marked read-only when it lacks tenant authority.
server:	tritond version, build, and git SHA, or unreachable with the cause.

whoami exits nonzero when the session is invalid or the server is unreachable. With -j or --format, it prints a single document with principal, endpoint, credential, and project, and prints nothing on failure.

See also

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