GlobalStacks logo GlobalStacks Reference
Open app
Reference

CLI Reference

Exact command reference for gstacks.

CLI reference

Use this page when you need exact command syntax.

Command namespaces in the operator CLI are singular. HTTP API endpoints use plural collection paths separately.

Each command card includes:

  • usage
  • flags
  • required values
  • defaults
  • examples when available

Use the CLI guide for task-based workflows. Use this page for exact command details.

auth
auth login

Validate a console-generated API key and store it in the local CLI config.

gstacks auth login --base-url URL --api-key KEY
Flags
  • --base-url Control plane base URL. Default: http://127.0.0.1:8080
  • --api-key Console-generated CLI API key. Required
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
Examples
gstacks auth login --base-url http://devops.local:8080 --api-key gsk_xxxxx
auth logout

Remove the local CLI config.

gstacks auth logout
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
whoami
whoami

Verify the configured API key and print the authenticated user payload.

gstacks whoami
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
version
version

Print the CLI version, branch, commit, and commit count.

gstacks version
upgrade
upgrade

Download and install the latest CLI release over the current binary.

gstacks upgrade
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --base-url Override upgrade source base URL.
  • --version Optional release version to install instead of latest.
  • --force Reinstall even when the current version already matches the target version.
Examples
gstacks upgrade
gstacks upgrade --version 0.1.339-6d0940d
gstacks upgrade --force
host
host list

List connected hosts from the infrastructure inventory.

gstacks host list
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
Examples
gstacks host list
host info

Show one host record with routing-relevant metadata such as tags, traits, ownership, and eligibility state.

gstacks host info --host-id ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --host-id Host identifier to inspect. Required
Examples
gstacks host info --host-id agt_123
host update

Update operator-managed host routing rules such as tags and eligibility flags. Ownership and classification remain control-plane managed.

gstacks host update --host-id ID [--tag TAG]
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --host-id Host identifier to update. Required
  • --tag Set operator-managed host tags; repeat flag to pass multiple.
  • --sandbox-eligible Set sandbox eligibility to true or false.
  • --host-access-eligible Set host terminal access eligibility to true or false.
Examples
gstacks host update --host-id agt_123 --tag pool:edge --sandbox-eligible true
host ssh

Open an interactive host shell session proxied through the connected host agent.

gstacks host ssh HOST
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --host-id Host identifier or name to connect to. Optional when provided positionally.
  • --session-id Existing terminal session to attach to.
  • --cols Requested terminal width. Default: 120
  • --rows Requested terminal height. Default: 32
Examples
gstacks host ssh devops
gstacks host ssh --host-id agent-123
gstacks host ssh devops --session-id aterm_123
host sessions

List current host shell sessions and whether they have an active viewer.

gstacks host sessions HOST
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --host-id Host identifier or name to inspect. Optional when provided positionally.
Examples
gstacks host sessions devops
host attach

Attach to an existing host shell session.

gstacks host attach HOST SESSION_ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
Examples
gstacks host attach devops aterm_123
volume
volume list

List control-plane volumes and summarize their current attachments.

gstacks volume list
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
Examples
gstacks volume list
volume info

Show one volume record as JSON, including attachment records and runtime state where available.

gstacks volume info ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
Examples
gstacks volume info vol_123
volume create

Create a detached control-plane volume.

gstacks volume create --cluster-id ID VOLUME_ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --cluster-id Cluster identifier to provision the volume in. Required
Examples
gstacks volume create --cluster-id cls_123 shared-media
volume attachment list

List attachment records for one volume.

gstacks volume attachment list ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
Examples
gstacks volume attachment list shared-media
volume attachment create

Create one attachment record for a volume.

gstacks volume attachment create ID --target-kind KIND --target-id TARGET
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --target-kind Attachment target kind. Required
  • --target-id Attachment target identifier. Required
  • --mount-path Target mount path when applicable.
  • --access-mode Attachment access mode.
  • --read-only Create the attachment as read-only.
Examples
gstacks volume attachment create shared-media --target-kind host --target-id agt_123
volume attachment delete

Delete one attachment record from a volume.

gstacks volume attachment delete ID ATTACHMENT
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
Examples
gstacks volume attachment delete shared-media volatt_123
sandbox
sandbox list

List tenant sandboxes from the infrastructure inventory. Archived sandboxes are hidden by default.

gstacks sandbox list
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --archived List archived sandboxes instead of active sandboxes.
  • --stopped List stopped sandboxes instead of active sandboxes.
Examples
gstacks sandbox list
gstacks sandbox list --archived
gstacks sandbox list --stopped
sandbox create

Create an empty sandbox and optionally constrain placement with host routing inputs.

gstacks sandbox create --cluster-id ID [--host-id ID] [--require-tag TAG] [--require-trait TRAIT]
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --name Optional sandbox name.
  • --image Optional base image reference.
  • --blueprint Active blueprint id or unique name to use as the sandbox source.
  • --cpu Requested vCPU count. Default: 0.5
  • --memory Requested memory. Default: 256MiB
  • --cluster-id Require placement in a specific cluster. Required
  • --host-id Require placement on a specific host.
  • --require-tag Require host tags for placement; repeat flag to pass multiple.
  • --require-trait Require host traits for placement; repeat flag to pass multiple.
  • --ssh Print the follow-up sandbox ssh command after creation.
Examples
gstacks sandbox create --cluster-id cls_123 --name buildbox
gstacks sandbox create --cluster-id cls_123 --blueprint dev-ready
gstacks sandbox create --cluster-id cls_123 --host-id agt_123 --require-trait docker --require-tag pool:edge
sandbox blueprint

Create a reusable blueprint from an existing sandbox.

gstacks sandbox blueprint SANDBOX --name NAME
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --sandbox-id Sandbox identifier or name to capture. Optional when provided positionally.
  • --name Blueprint name. Required
  • --description Blueprint description.
Examples
gstacks sandbox blueprint devbox --name captured-devbox
sandbox info

Show one sandbox record as JSON.

gstacks sandbox info ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --sandbox-id Sandbox identifier to inspect. Optional when provided positionally.
Examples
gstacks sandbox info sbx_123
gstacks sandbox info --sandbox-id sbx_123
sandbox delete

Deprovision a sandbox runtime and archive the sandbox record.

gstacks sandbox delete ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --sandbox-id Sandbox identifier to deprovision. Optional when provided positionally.
Examples
gstacks sandbox delete sbx_123
gstacks sandbox delete --sandbox-id sbx_123
sandbox stop

Stop one sandbox runtime.

gstacks sandbox stop ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --sandbox-id Sandbox identifier to stop. Optional when provided positionally.
Examples
gstacks sandbox stop sbx_123
gstacks sandbox stop --sandbox-id sbx_123
sandbox start

Start one stopped sandbox runtime.

gstacks sandbox start ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --sandbox-id Sandbox identifier to start. Optional when provided positionally.
Examples
gstacks sandbox start sbx_123
gstacks sandbox start --sandbox-id sbx_123
sandbox fork

Create one sandbox fork.

gstacks sandbox fork [--name NAME] --mode MODE SANDBOX_ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --sandbox-id Sandbox identifier to fork. Optional when provided positionally.
  • --name Optional child sandbox name.
  • --mode Fork mode (filesystem or live). Required
  • --fallback Fallback mode when live fork is not possible. One of: none, filesystem. Default: none
  • --purpose Fork purpose. One of: branch, speculative, debug, review, temporary. Default: branch
  • --ttl Optional TTL for disposable forks in seconds. Default: 0
  • --count Number of forks to create. Default: 1
Examples
gstacks sandbox fork sbx_123 --mode filesystem --name feature-auth
gstacks sandbox fork sbx_123 --mode filesystem --name speculative --count 3
gstacks sandbox fork --mode live --fallback filesystem --name quick-check sbx_123
sandbox forks

List forks created from one sandbox.

gstacks sandbox forks SANDBOX_ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --sandbox-id Sandbox identifier whose forks should be listed. Optional when provided positionally.
Examples
gstacks sandbox forks sbx_123
gstacks sandbox forks --sandbox-id sbx_123
sandbox lineage

Show root, ancestor, current, and descendant fork lineage for one sandbox.

gstacks sandbox lineage SANDBOX_ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --sandbox-id Sandbox identifier whose lineage should be shown. Optional when provided positionally.
Examples
gstacks sandbox lineage sbx_123
gstacks sandbox lineage --sandbox-id sbx_123
sandbox ssh

Open an interactive sandbox terminal.

gstacks sandbox ssh ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --sandbox-id Sandbox identifier to connect to. Optional when provided positionally.
  • --session-id Existing terminal session to attach to.
  • --cols Requested terminal width. Default: 120
  • --rows Requested terminal height. Default: 32
Examples
gstacks sandbox ssh sbx_123
gstacks sandbox ssh --sandbox-id sbx_123
gstacks sandbox ssh sbx_123 --session-id sterm_123
sandbox sessions

List current sandbox shell sessions and whether they have an active viewer.

gstacks sandbox sessions ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --sandbox-id Sandbox identifier to inspect. Optional when provided positionally.
Examples
gstacks sandbox sessions sbx_123
sandbox attach

Attach to an existing sandbox shell session.

gstacks sandbox attach ID SESSION_ID
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
Examples
gstacks sandbox attach sbx_123 sterm_123
blueprint
blueprint list

List sandbox blueprints and their source artifact references.

gstacks blueprint list
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
Examples
gstacks blueprint list
blueprint create

Create an image-backed blueprint from an external image source.

gstacks blueprint create IMAGE --name NAME [--registry REGISTRY]
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --name Blueprint name. Required
  • --description Blueprint description.
  • --registry Registry connection id for the source image.
Examples
gstacks blueprint create ghcr.io/acme/dev:latest --name dev-ready --registry reg_123
blueprint get

Show one blueprint as JSON.

gstacks blueprint get BLUEPRINT
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
blueprint activate

Mark a blueprint active for sandbox creation.

gstacks blueprint activate BLUEPRINT
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
blueprint deactivate

Mark a blueprint inactive.

gstacks blueprint deactivate BLUEPRINT
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
blueprint delete

Delete a blueprint record.

gstacks blueprint delete BLUEPRINT
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
registry
registry list

List external registry connections.

gstacks registry list
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
registry create

Create an external registry connection for image-backed blueprints.

gstacks registry create NAME [--provider PROVIDER] [--url URL]
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --provider Registry provider.
  • --url Registry URL.
  • --username Registry username.
  • --credential-secret-ref Secret reference for registry credentials.
  • --project Registry project, namespace, or account.
  • --insecure-skip-tls-verify Skip TLS verification for this registry connection.
Examples
gstacks registry create ghcr --provider ghcr --url https://ghcr.io --username robot --credential-secret-ref secret://registry/ghcr
registry get

Show one registry connection as JSON.

gstacks registry get REGISTRY
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
registry update

Update an external registry connection.

gstacks registry update REGISTRY [--name NAME]
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --name Registry connection name.
  • --provider Registry provider.
  • --url Registry URL.
  • --username Registry username.
  • --credential-secret-ref Secret reference for registry credentials.
  • --project Registry project, namespace, or account.
  • --insecure-skip-tls-verify Skip TLS verification for this registry connection.
registry delete

Delete an external registry connection.

gstacks registry delete REGISTRY
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
registry status

Show internal blueprint registry settings as JSON.

gstacks registry status
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
registry repositories

List internal blueprint registry repositories.

gstacks registry repositories
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
registry artifacts

List internal blueprint registry artifacts.

gstacks registry artifacts
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
network
network list

List runtime networks.

gstacks network list
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
Examples
gstacks network list
network create

Create a runtime network.

gstacks network create --cluster-id ID NAME
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --cluster-id Cluster identifier to provision the network in. Required
  • --slug DNS-safe network slug.
  • --dns-domain Network DNS suffix.
Examples
gstacks network create --cluster-id cls_123 dev
network inspect

Show one runtime network as JSON.

gstacks network inspect NETWORK
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
network attach

Attach a sandbox to a network and publish an alias.

gstacks network attach NETWORK SANDBOX --alias NAME --port PORT
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --alias DNS alias to publish on the network. Required
  • --port Port to expose for the alias; repeat to pass multiple. Required
Examples
gstacks network attach dev sbx_123 --alias api --port 8080
network detach

Detach a sandbox from a network.

gstacks network detach NETWORK SANDBOX
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
network alias list

List network aliases.

gstacks network alias list NETWORK
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
network alias add

Add an alias to a sandbox network member.

gstacks network alias add NETWORK SANDBOX ALIAS --port PORT
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --port Port to expose for the alias; repeat to pass multiple. Required
Examples
gstacks network alias add dev sbx_123 worker --port 9090
network alias remove

Remove a network alias.

gstacks network alias remove NETWORK ALIAS
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
network policy list

List network policies.

gstacks network policy list NETWORK
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
network policy allow

Allow traffic within a network.

gstacks network policy allow NETWORK --from SOURCE --to TARGET --port PORT
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --from Source alias or selector. Required
  • --to Target alias or selector. Required
  • --port Allowed port; repeat to pass multiple. Required
Examples
gstacks network policy allow dev --from local --to api --port 8080
network resolve

Resolve a network alias.

gstacks network resolve NETWORK NAME
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
network test

Test whether a network route is allowed by policy.

gstacks network test NETWORK SOURCE TARGET:PORT
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
Examples
gstacks network test dev local api:8080
mesh
mesh join

Join a network from this machine.

gstacks mesh join NETWORK
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --state-dir Directory for local mesh state. Default: ~/.config/gstacks/mesh
Examples
gstacks mesh join dev
mesh status

Show local mesh join status.

gstacks mesh status [NETWORK]
Flags
  • --state-dir Directory for local mesh state. Default: ~/.config/gstacks/mesh
mesh forward

Forward a local port to one network service.

gstacks mesh forward NETWORK ALIAS:PORT --local PORT
Flags
  • --config-file Path to the persisted CLI config file. Default: ~/.config/gstacks/config.json
  • --state-dir Directory for local mesh state. Default: ~/.config/gstacks/mesh
  • --local Local TCP port to listen on. Required
Examples
gstacks mesh forward dev api:8080 --local 18080
completion
completion bash

Generate a Bash completion script.

gstacks completion bash
completion zsh

Generate a Zsh completion script.

gstacks completion zsh
completion fish

Generate a Fish completion script.

gstacks completion fish
completion powershell

Generate a PowerShell completion script.

gstacks completion powershell
Previous
CLI
Next
API and Contracts