GantryCD
CLI reference
GantryCD administrative CLI.
See Automation for authentication and the SDK.
gantrycli cloud-integrations
Manage a stack’s access to cloud providers
gantrycli cloud-integrationsgantrycli cloud-integrations delete
Revoke a stack’s access to a cloud provider
gantrycli cloud-integrations delete <provider-type> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli cloud-integrations get
Show a stack’s integration with one cloud provider
gantrycli cloud-integrations get <provider-type> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli cloud-integrations list
List a stack’s cloud integrations
gantrycli cloud-integrations list [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli cloud-integrations update
Set the whole configuration of a stack’s integration with one provider, creating the integration if the stack has none yet.
It is a replacement, not a merge: for AWS, the —aws-role flags you pass become the stack’s complete set of roles, so a role you leave out is removed. Pass every role you want the stack to keep.
gantrycli cloud-integrations update <provider-type> [flags]Flags:
--aws-role stringArray An IAM role for the stack, as name=<profile>,role_arn=<arn>[,inline_policy=<json|@file>]. Repeat for each role; the name is the profile the stack's OpenTofu selects it by, and a role named "default" serves an aws provider block with no profile. inline_policy must come last (it is JSON, so it contains commas). Required when --provider=aws.
--gcp-service-account-email string GCP service account to impersonate (required when --provider=gcp)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli completion bash
Generate the autocompletion script for the bash shell.
This script depends on the ‘bash-completion’ package. If it is not installed already, you can install it via your OS’s package manager.
To load completions in your current shell session:
source <(gantrycli completion bash)To load completions for every new session, execute once:
Linux:
gantrycli completion bash > /etc/bash_completion.d/gantryclimacOS:
gantrycli completion bash > $(brew --prefix)/etc/bash_completion.d/gantrycliYou will need to start a new shell for this setup to take effect.
gantrycli completion bashFlags:
--no-descriptions disable completion descriptionsgantrycli completion fish
Generate the autocompletion script for the fish shell.
To load completions in your current shell session:
gantrycli completion fish | sourceTo load completions for every new session, execute once:
gantrycli completion fish > ~/.config/fish/completions/gantrycli.fishYou will need to start a new shell for this setup to take effect.
gantrycli completion fish [flags]Flags:
--no-descriptions disable completion descriptionsgantrycli completion powershell
Generate the autocompletion script for powershell.
To load completions in your current shell session:
gantrycli completion powershell | Out-String | Invoke-ExpressionTo load completions for every new session, add the output of the above command to your powershell profile.
gantrycli completion powershell [flags]Flags:
--no-descriptions disable completion descriptionsgantrycli completion zsh
Generate the autocompletion script for the zsh shell.
If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:
echo "autoload -U compinit; compinit" >> ~/.zshrcTo load completions in your current shell session:
source <(gantrycli completion zsh)To load completions for every new session, execute once:
Linux:
gantrycli completion zsh > "${fpath[1]}/_gantrycli"macOS:
gantrycli completion zsh > $(brew --prefix)/share/zsh/site-functions/_gantrycliYou will need to start a new shell for this setup to take effect.
gantrycli completion zsh [flags]Flags:
--no-descriptions disable completion descriptionsgantrycli configure
Writes a profile’s connection settings. The target is the active profile selector (—profile / GANTRYCD_PROFILE) or “default”.
Run gantrycli login after configure to authenticate.
gantrycli configure [flags]Flags:
--api-url string Backend API URL (e.g. https://gantrycd.example.com)
--org string Default organization id for commands that require --org
--output format Output format: text or json (default text)
--set-active Make this the active profile (default true)gantrycli contexts
Manage org-level shared variable bundles (contexts)
gantrycli contextsgantrycli contexts create
Create a context with an optional starting set of environment variables.
Attach it to a stack afterwards with gantrycli stacks contexts replace.
gantrycli contexts create [flags]Flags:
--auto-attach-priority int Priority ordering auto-attached contexts on a stack; higher wins on a conflicting key (ignored without --auto-attach-selector)
--auto-attach-selector stringArray Stack-label selector as key=value that auto-attaches this context to matching stacks (may be repeated; omit to disable auto-attach)
--name string Context name (required)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--sensitive-var stringArray Sensitive environment variable as key=value (may be repeated)
--var stringArray Environment variable as key=value (may be repeated)gantrycli contexts delete
Delete a context. Stacks still referencing it lose those variables
immediately — check gantrycli contexts referencing-stacks first.
gantrycli contexts delete <context-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli contexts env
Manage a context’s environment variables
gantrycli contexts envgantrycli contexts env list
List a context’s environment variables
gantrycli contexts env list <context-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli contexts env replace
Full replacement: the set you pass becomes the context’s complete list of variables — any key already set but omitted here is deleted. Pass —clear with no —var/—sensitive-var to wipe them all.
gantrycli contexts env replace <context-id> [flags]Flags:
--clear Remove all of the context's environment variables
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--sensitive-var stringArray Sensitive environment variable as key=value (may be repeated)
--var stringArray Environment variable as key=value (may be repeated)gantrycli contexts get
Show a single context
gantrycli contexts get <context-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli contexts list
List contexts in an org
gantrycli contexts list [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli contexts referencing-stacks
List the stacks that reference a context
gantrycli contexts referencing-stacks <context-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli contexts update
Update a context’s name and auto-attach selector/priority
gantrycli contexts update <context-id> [flags]Flags:
--auto-attach-priority int Priority ordering auto-attached contexts on a stack; higher wins on a conflicting key
--auto-attach-selector stringArray Stack-label selector as key=value that auto-attaches this context to matching stacks (may be repeated; replaces the current selector, pass none to leave it unchanged, use --clear-auto-attach to disable)
--clear-auto-attach Disable auto-attach by clearing the selector
--name string New context name (required)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli deployments
Inspect, create, confirm, cancel deployments; stream logs and plan/state artifacts
gantrycli deploymentsgantrycli deployments cancel
Request cancellation of a deployment
gantrycli deployments cancel <deployment-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli deployments confirm
Confirm the next stage of a deployment (apply, replan, or skip)
gantrycli deployments confirm <deployment-id> [flags]Flags:
--action string apply | replan | skip (default "apply")
--exclude strings OpenTofu resource address to exclude; repeat for multiple (only with --action=replan; mutually exclusive with --target)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--replace strings OpenTofu resource address to force-replace; repeat for multiple (only with --action=replan)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)
--target strings OpenTofu resource address to target; repeat for multiple (only with --action=replan; mutually exclusive with --exclude)gantrycli deployments create
Trigger a new deployment (plan, destroy, or refresh)
gantrycli deployments create [flags]Flags:
-f, --follow Stream run logs as they appear (implies --wait)
--interval duration Poll interval for --wait and --follow (default 3s)
--mode string Deployment mode: plan, destroy, or refresh (default "plan")
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)
--wait Block until the deployment reaches a terminal stategantrycli deployments get
Show a single deployment with its stages
gantrycli deployments get <deployment-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli deployments graph
OpenTofu’s own resource-to-resource dependency graph (explicit depends_on plus inferred references), derived from the stack’s configuration at plan time. Distinct from the cross-stack gantrycd:dependency: edges that drive dependent triggers.
gantrycli deployments graph <run-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli deployments list
List deployments on a stack (newest first)
gantrycli deployments list [flags]Flags:
--limit int Maximum deployments to return (1..100, default 50)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli deployments logs
Streams the run’s log as raw bytes to stdout, optionally following new chunks as they appear. Always streams raw log bytes; —output/json is not supported for this command — it’s a continuous, unbounded stream.
gantrycli deployments logs <run-id> [flags]Flags:
-f, --follow Keep polling for new chunks until the run terminates
--interval duration Poll interval when --follow is set (default 1s)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli deployments plan-changes
Per-resource change detail from a plan-style run — the same content
tofu plan printed for each resource block, the thing to review before
deployments confirm. Same 404 contract as plan-summary; payloads can
be large for big plans.
gantrycli deployments plan-changes <run-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli deployments plan-summary
Shows has_changes and the per-action resource counts the runner parsed
from tofu plan. Only produced by plan-style runs (plan, destroy,
refresh) — a 404 typically means the run was an apply, or failed before
producing a plan.
gantrycli deployments plan-summary <run-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli deployments prioritize
Bump a deployment ahead of FIFO queue order, at both queue layers: its stack’s deployment lane and the runner queue. Waiting work only — the deployment currently running on the stack is never preempted, and a bump cannot conjure runner capacity; it decides who gets the next free slot. Among prioritized deployments, ordering is FIFO by bump time; repeating the command keeps the original bump timestamp.
gantrycli deployments prioritize <deployment-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--remove return the deployment to normal FIFO queue order
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli deployments retry
Retries a terminal deployment by creating a new deployment that mirrors the original’s mode, origin, and commit. For PR-origin deployments the PR row’s latest_deployment_id is repointed at the new run so the pull-requests view surfaces it.
gantrycli deployments retry <deployment-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli deployments skip
Skip a deployment (the run is not executed; queue advances)
gantrycli deployments skip <deployment-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli deployments skip-all
Skip every pending deployment on the stack (returns the count)
gantrycli deployments skip-all [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli deployments state
For a plan-style run this reflects the prior (refreshed) state; for an apply run it reflects the post-apply state. Attribute values are omitted in text mode — use —output json to see them (sensitive values are already redacted server-side).
gantrycli deployments state <run-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli deployments wait
Polls GET /deployments/{id} until status is one of finished, failed, cancelled, skipped. Exit code mirrors the outcome: 0 finished, 1 failed, 2 cancelled, 3 skipped. A poll-time error (auth, not-found, …) uses a separate mapping — see the Automation guide’s Exit codes section.
gantrycli deployments wait <deployment-id> [flags]Flags:
--interval duration Poll interval between status checks (default 3s)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli group-role-bindings
Manage SSO group<->role bindings
gantrycli group-role-bindingsgantrycli group-role-bindings create
Bind an SSO group to one or more roles
gantrycli group-role-bindings create [flags]Flags:
--group-key string SSO group key (required)
--identity-source-id string Identity source id (required)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--role-key gantrycli roles list Role key to bind, from gantrycli roles list (may be repeated; at least one required)gantrycli group-role-bindings delete
Delete a group-role binding
gantrycli group-role-bindings delete [flags]Flags:
--id string Group-role binding id (required)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli group-role-bindings list
List group-role bindings in an org
gantrycli group-role-bindings list [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli group-role-bindings update
Full replacement: the —role-key set you pass becomes the binding’s complete role set — any role bound but omitted here is unbound.
gantrycli group-role-bindings update [flags]Flags:
--id string Group-role binding id (required)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--role-key gantrycli roles list Role key to bind, from gantrycli roles list (may be repeated; full replacement, at least one required)gantrycli local-plan
Packs the current git repository (tracked + untracked files, respecting .gitignore — uncommitted changes included), uploads it, and runs a plan-only deployment against the stack. The plan can never be applied or retried; push and deploy normally once the changes look right.
Run it from inside the repository the stack tracks. Requires the (stack, local_deploy) permission.
gantrycli local-plan <stack-id> [flags]Flags:
--follow Stream run logs as they appear (implies --wait); use --follow=false to detach (default true)
--interval duration Poll interval for --wait and --follow (default 3s)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--wait Block until the deployment reaches a terminal stategantrycli login
Authenticates the active profile (or the one named with —profile) and caches the credential in ~/.gantrycd/credentials.yaml.
Pass —api-url to configure and authenticate in one step without a prior
gantrycli configure call. Pass —org to set the default organization.
Without —token-stdin, login fetches the server’s SSO providers, lets you pick one when there are several, then opens your browser to complete the OAuth flow.
With —token-stdin, login reads a personal-access-token or service-account token from stdin — no browser, for CI / SSH / containers.
gantrycli login [flags]Flags:
--api-url string Backend API URL — configure and login in one step
--org string Default organization id to save to the profile
--output format Output format: text or json (default text)
--token-stdin Read a static token from stdin instead of opening a browsergantrycli logout
Drops the cached token for the active profile (or —profile) from ~/.gantrycd/credentials.yaml. For an SSO session it also revokes the session server-side, best-effort, so a leaked credentials file can’t be reused.
gantrycli logout [flags]Flags:
--output format Output format: text or json (default text)gantrycli operator
Direct database operator commands
gantrycli operatorgantrycli operator advanced
Advanced operator commands (development, perf testing, recovery)
gantrycli operator advancedgantrycli operator advanced loadtest
Seed the database (and rustfs) with synthetic load-test data
gantrycli operator advanced loadtestgantrycli operator advanced loadtest seed
Seed the database (and rustfs) with synthetic data for performance testing.
Defaults are sized for laptop runs. The big numbers from the original feature request — 100k orgs, 100k users/org, 10k stacks/org — are valid invocations but must be passed explicitly:
gantrycli operator advanced loadtest seed
—orgs=100000 —users-per-org=100000 —sessions-per-user=100
—stacks-per-org=10000 —yes
The first —loginable-orgs orgs (default 10) are wired to the local keycloak realm groups (gantrycd-admins, gantrycd-users, Tech_Backend, Tech_Infra) so alice and bob can actually log in and exercise the SSO+authz path. The rest use synthetic group keys and exist purely for row-count stress.
When —perf-org is set (default), the seeder also creates a single perf-test org with two stacks: one with —perf-deployments deployments (plan + apply runs, mixed statuses) and one with a single deployment whose plan and apply logs each consume —perf-log-bytes (default 1 GiB) in rustfs through the existing chunk system.
All IDs are deterministic and prefixed with —id-prefix. Re-running the command resumes where it left off without producing duplicates.
Required environment: DATABASE_URL Postgres write URL. GANTRYCD_DATA_ENCRYPTION_* Same data-encryption config as the backend (PROVIDER + provider keys), used to encrypt OIDC client secrets on identity_source rows. LOGS_S3_* Logs S3/rustfs settings (only required when —perf-org is set).
gantrycli operator advanced loadtest seed [flags]Flags:
--batch-size int rows per write transaction inside a single org (default 500)
--group-bindings-per-source int group→role bindings per identity source (default 4)
--id-prefix string deterministic prefix for every generated ID — also drives --reset (default "loadtest")
--identity-sources-per-org int identity sources created per bulk org (default 1)
--loginable-orgs int first N bulk orgs use real keycloak group keys so alice/bob can log in (default 10)
--oidc-issuer string OIDC issuer URL recorded on each generated identity source (default "http://localhost:8081/realms/gantrycd")
--orgs int number of bulk orgs to seed (default 100)
--perf-deployments int deployments in the perf-test org's stack-many-deployments (default 100000)
--perf-log-bytes int bytes per stage log in stack-big-logs (default 1 GiB; produces 2 GiB total) (default 1073741824)
--perf-org also seed the special perf-test org with deployments and big logs (default true)
--reset delete all rows whose IDs start with --id-prefix before seeding
--runner-groups-per-org int runner groups created per bulk org (default 2)
--runners-per-group int runners created per runner group (default 3)
--scm-integrations-per-org int SCM integrations created per bulk org (default 2)
--sessions-per-user int sessions created per user (default 5)
--stacks-per-org int stacks created per bulk org (no runs) (default 20)
--users-per-org int users created per bulk org (default 50)
--workers int concurrent goroutines for the bulk-org loop (default 8)
--yes skip the size-confirmation prompt for very large invocationsgantrycli operator advanced sample-dependencies
Populates an organization with cross-stack dependency edges for each shape the cycle detector handles — mutual reads, a shared hub, a long ring, a bowtie, a diamond, one-way reads, mixed endpoint kinds and an intra-stack edge — so each can be inspected in the Dependencies view. Dev-only; bypasses authz.
gantrycli operator advanced sample-dependencies [flags]Flags:
--org string target organization ID (required)gantrycli operator advanced sample-explore
Populates an existing organization with synthetic Terraform resources so the Explore view and the stack Resources tab can be exercised locally. Writes the stacks, the S3 analysis.json artifacts (so resource detail loads), and the explore index rows — all consistent. Dev-only; bypasses authz.
gantrycli operator advanced sample-explore [flags]Flags:
--org string target organization ID (required)
--per-stack int resources per stack (default 300)
--stacks int number of sample stacks (the first 8 use curated names, then sample-stack-N) (default 8)gantrycli operator memberships
Manage org memberships directly in the database
gantrycli operator membershipsgantrycli operator memberships revoke
Immediately revoke a user’s org membership
gantrycli operator memberships revoke [flags]Flags:
--org-id string org ID to revoke membership from
--user-id string user ID to revoke membership forgantrycli operator organizations
Manage organizations directly in the database
gantrycli operator organizationsgantrycli operator organizations create
Create a standard (shared) organization
gantrycli operator organizations create [flags]Flags:
--handle string login-start handle for the organization
--id string organization id (defaults to --handle)gantrycli operator service-accounts
Manage service accounts directly in the database
gantrycli operator service-accountsgantrycli operator service-accounts assign-role
Grant a role to a service account
gantrycli operator service-accounts assign-role [flags]Flags:
--org-id string organization id the service account belongs to
--role string role key to grant (default "admin")
--service-account string service account idgantrycli operator service-accounts create
Create a standalone service account
gantrycli operator service-accounts create [flags]Flags:
--name string service account name
--org-id string organization id the service account belongs togantrycli operator service-accounts create-token
Mint a long-lived API token for a service account
gantrycli operator service-accounts create-token [flags]Flags:
--expires string token lifetime: a Go duration (e.g. 24h, 720h) or "unlimited" (default "24h")
--name string token name
--org-id string organization id the service account belongs to
--service-account string service account idgantrycli operator users
Manage users directly in the database
gantrycli operator usersgantrycli operator users assign-role
Grant a role to a user in an org
gantrycli operator users assign-role [flags]Flags:
--org-id string organization id
--role string role key to grant (default "admin")
--user-id string user idgantrycli operator users create
Create a user with a synthetic identity (provider prefix “test”) and add them as a manual member of the given org, bypassing SSO entirely. This is a break-glass tool for provisioning a real human-user principal — e.g. to mint a PAT that authenticates as a human, for endpoints the API blocks for service-account tokens — not a way to onboard real users.
gantrycli operator users create [flags]Flags:
--org-id string organization id to add the user to
--username string user display namegantrycli operator users create-token
Mint a PAT for a user directly against the database. The public API only
allows minting a PAT from an authenticated browser session
(sessionRouteDenyPAT), which a non-interactive CLI/CI context can never
obtain — this break-glass command is the direct-DB equivalent, the same way
operator service-accounts create-token mints service-account credentials.
gantrycli operator users create-token [flags]Flags:
--expires string token lifetime: a Go duration (e.g. 24h, 720h) or "unlimited" (default "24h")
--name string token name
--org-id string organization id the token is scoped to
--user-id string user idgantrycli operator users demote-super-admin
Revoke a user’s system-wide super-admin role
gantrycli operator users demote-super-admin [flags]Flags:
--user-id string user ID to demote (form: <provider_prefix>:<idp_username>:<idp_subject>)gantrycli operator users promote-super-admin
Grant a user the system-wide super-admin role
gantrycli operator users promote-super-admin [flags]Flags:
--user-id string user ID to promote (form: <provider_prefix>:<idp_username>:<idp_subject>)gantrycli orgs
List and inspect organizations the caller can access
gantrycli orgsgantrycli orgs get
Show a single organization
gantrycli orgs get <org-id> [flags]Flags:
--output format Output format: text or json (default text)gantrycli orgs list
List orgs the caller is a member of (super-admin sees all)
gantrycli orgs list [flags]Flags:
--output format Output format: text or json (default text)gantrycli orgs protected-labels
Manage the org’s protected stack-label-key policy
gantrycli orgs protected-labelsgantrycli orgs protected-labels get
Show the org’s protected stack-label keys
gantrycli orgs protected-labels get [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli orgs protected-labels set
Full replacement: pass —key for every label key that should be protected (may be repeated). Pass —clear with no —key to remove all protected labels.
gantrycli orgs protected-labels set [flags]Flags:
--clear Remove all protected labels
--key stringArray Protected stack-label key (may be repeated)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli pats
Read-only. Minting and revoking PATs requires a browser session (the backend rejects PAT-authenticated calls on those routes so a leaked token can’t mint peers or revoke the one you’d use to rotate it). Use the web UI under /profile/tokens.
gantrycli patsgantrycli pats list
List your personal access tokens (no raw token values)
gantrycli pats list [flags]Flags:
--output format Output format: text or json (default text)gantrycli ping
Probe the backend’s /health endpoint (no auth required)
gantrycli ping [flags]Flags:
--output format Output format: text or json (default text)
--timeout duration HTTP timeout (default 5s)gantrycli profile
List, inspect, and switch CLI profiles
gantrycli profilegantrycli profile list
List configured profiles (active one marked with *)
gantrycli profile list [flags]Flags:
--output format Output format: text or json (default text)gantrycli profile show
Show a profile’s settings (no secrets); defaults to the active profile
gantrycli profile show [name] [flags]Flags:
--output format Output format: text or json (default text)gantrycli profile use
Set the active profile
gantrycli profile use <name> [flags]Flags:
--output format Output format: text or json (default text)gantrycli queue
Show the org’s deployment work that has a non-terminal run, scoped to the
stacks you can read, in the order it executes: first runs executing on a runner
(longest-running first), then runs waiting for a free runner slot (in dispatch
order — prioritized first, then FIFO), then deployments queued behind their
stack’s single active lane. Only the last two can be reordered; bump one with:
gantrycli deployments prioritize
A deployment held at a confirmation gate has no run, so it is not listed here even though it holds its stack’s lane; rows queued behind one name it.
gantrycli queue [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli role-assignments
Manage direct user<->role grants
gantrycli role-assignmentsgantrycli role-assignments assign
Grant a role directly to a user
gantrycli role-assignments assign [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--role-key gantrycli roles list Role key to grant, from gantrycli roles list (required)
--user-id string User id to grant the role to (required)gantrycli role-assignments list
List role assignments in an org
gantrycli role-assignments list [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli role-assignments revoke
Revoke a role assignment
gantrycli role-assignments revoke [flags]Flags:
--id string Role assignment id (required)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli roles
Manage org RBAC roles (system + custom)
gantrycli rolesgantrycli roles create
Create a custom role with at least one permission.
Permissions are given as repeated —permission resource_type:action[:pattern] flags, e.g. —permission stack:read —permission stack:deploy:prod-. pattern is a glob ("" = any, ”?” = one char); omit it for “any resource of that type”.
The response includes the role’s server-derived key — that key (not the
UUID id) is what role-assignments assign --role-key and
group-role-bindings create/update --role-key reference.
gantrycli roles create [flags]Flags:
--description string Role description
--name string Role name (required)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--permission stringArray Permission as resource_type:action[:pattern] (may be repeated). pattern is a glob ("*" = any, "?" = one char); omit it for "any resource of that type". At least one is required.gantrycli roles delete
Delete a custom role by its —id (UUID). System roles cannot be deleted — the server rejects it.
Deleting a role cascades server-side: any role-assignments or group-role-bindings that still reference it are silently removed along with it, not something this command controls.
gantrycli roles delete [flags]Flags:
--id string Role id, UUID (required)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli roles list
List roles available in an org (system + custom)
gantrycli roles list [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli roles update
Update a custom role. —id is the role’s UUID id (see roles list --output json, or the id printed by roles create) — not its key.
This is a full replacement, same shape as create: —name, —description, and every —permission the role should end up with must all be passed, even ones that aren’t changing. Permission syntax: resource_type:action[:pattern].
System roles cannot be updated — the server rejects it; this command only works on custom roles.
gantrycli roles update [flags]Flags:
--description string Role description
--id string Role id, UUID (required)
--name string Role name
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--permission stringArray Permission as resource_type:action[:pattern] (may be repeated). pattern is a glob ("*" = any, "?" = one char); omit it for "any resource of that type". Full replacement; at least one is required.gantrycli runner-groups
Manage runner groups: inspect, create/update, rotate keys, set the org default
gantrycli runner-groupsgantrycli runner-groups create
Create a runner group of type github-actions. GantryCD dispatches a workflow_dispatch event on the configured repository every time a queued run matches this group’s labels; the workflow plays the runner role over the standard HTTP protocol.
Self-hosted groups are intentionally NOT createable from the CLI: their flow returns a one-time private key that should not pass through stdout. Use the web UI or the Terraform provider’s write-only attribute for those.
gantrycli runner-groups create [flags]Flags:
--github-app-id int GitHub App ID
--github-app-private-key-file string Path to the GitHub App private key PEM file
--github-repo string GitHub repository owner/name (e.g. acme/infra)
--github-workflow string Workflow filename under .github/workflows/ (default "gantrycd-runner.yaml")
--github-workflow-ref string Git ref to dispatch the workflow at (default "main")
--label strings Label as key=value (may be repeated). A stack's gantrycd:runner-group:* selector must be a subset of these for this group to claim its runs.
--max-concurrent int Maximum simultaneously in-flight runs in this group (default 5)
--name string Runner group name (required)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--type string Runner group type (only 'github-actions' is supported from the CLI) (default "github-actions")gantrycli runner-groups delete
Delete a runner group. Stacks selecting this group by gantrycd:runner-group: label stop matching any group until repointed; if it’s also the org default, unset that first (see set-default —clear).
gantrycli runner-groups delete <group-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli runner-groups get
Show a single runner group
gantrycli runner-groups get <group-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli runner-groups get-default
The default runner group runs stacks that set no gantrycd:runner-group: labels.
gantrycli runner-groups get-default [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli runner-groups list
List runner groups in an org
gantrycli runner-groups list [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli runner-groups rotate-key
The new PEM-encoded private key is printed once to stdout — capture it and re-deploy it to the runner. Existing 10-minute JWTs signed with the old key expire naturally.
gantrycli runner-groups rotate-key <group-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli runner-groups set-default
The default runner group runs stacks that set no gantrycd:runner-group: labels. Pass a group id to set it, or —clear to remove the default (empty-selector stacks then match any group).
gantrycli runner-groups set-default <group-id> [flags]Flags:
--clear Clear the org's default runner group instead of setting one.
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli runner-groups update
Update a runner group. —label may be repeated and always replaces the current set. For github-actions groups, pass —github-repo together with the other github-app flags to replace the provider config in the same write transaction; the backend-managed signing keypair is preserved.
Self-hosted groups accept only —label updates here. To update credentials on a self-hosted group, rotate the key (gantrycli runner-groups rotate-key).
gantrycli runner-groups update <group-id> [flags]Flags:
--github-app-id int GitHub App ID
--github-app-private-key-file string Path to the GitHub App private key PEM file (re-required on every github_config update)
--github-repo string GitHub repository owner/name (presence implies a github-actions config update)
--github-workflow string Workflow filename under .github/workflows/ (default "gantrycd-runner.yaml")
--github-workflow-ref string Git ref to dispatch the workflow at (default "main")
--label strings Label as key=value (may be repeated). Replaces the existing label set.
--max-concurrent int Maximum simultaneously in-flight runs in this group (default 5)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli runners
List and force-remove individual runner processes
gantrycli runnersgantrycli runners delete
Without —force the backend refuses to drop a runner with an unfinished state — pass —force only after confirming the worker process is dead, otherwise an active run can be orphaned.
gantrycli runners delete <runner-id> [flags]Flags:
--force Bypass the unfinished-run guard (use only after confirming the worker is gone)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli runners list
List runners in an org, optionally filtered by —group
gantrycli runners list [flags]Flags:
--group string Restrict to one runner group id
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli service-accounts
Manage org-level service accounts: create/list/get/update/delete, role assignments, tokens
gantrycli service-accountsgantrycli service-accounts create
Create a standalone service account
gantrycli service-accounts create [flags]Flags:
--name string Service account name (required)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli service-accounts delete
Delete a service account
gantrycli service-accounts delete <service-account-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli service-accounts get
Show a single service account
gantrycli service-accounts get <service-account-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli service-accounts list
List service accounts in an org
gantrycli service-accounts list [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli service-accounts role-assignments
Manage the roles assigned to a service account
gantrycli service-accounts role-assignmentsgantrycli service-accounts role-assignments assign
Assign a role to a service account
gantrycli service-accounts role-assignments assign <service-account-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--role-key string Role key to assign (required)gantrycli service-accounts role-assignments list
List the roles assigned to a service account
gantrycli service-accounts role-assignments list <service-account-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli service-accounts role-assignments revoke
Revoke a role assignment from a service account
gantrycli service-accounts role-assignments revoke <service-account-id> [flags]Flags:
--assignment-id string Role assignment id to revoke (required)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli service-accounts tokens
Manage API tokens issued to a service account
gantrycli service-accounts tokensgantrycli service-accounts tokens create
The raw token is printed once to stdout — capture it now, it is never shown again (list only ever returns the token_prefix).
gantrycli service-accounts tokens create <service-account-id> [flags]Flags:
--expires-in string Token lifetime, e.g. "8760h", or the literal "unlimited" (required)
--name string Token name (required)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli service-accounts tokens delete
Revoke a service account token
gantrycli service-accounts tokens delete <service-account-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--token-id string Token id to revoke (required)gantrycli service-accounts tokens list
List tokens issued to a service account (no raw token values — there aren’t any in this response)
gantrycli service-accounts tokens list <service-account-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli service-accounts update
IsDisabled is the only mutable field a service account exposes (name and org are fixed at creation) and it has no omitempty, so it is always sent: pass —disabled to disable the account, or —disabled=false (the default) to (re-)enable it.
gantrycli service-accounts update <service-account-id> [flags]Flags:
--disabled Disable (true) or enable (false, default) the service account
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli stacks
List, inspect, force-sync stacks, and manage their environment/contexts
gantrycli stacksgantrycli stacks contexts
A stack references contexts as an ordered list; at deploy time the
contexts are merged in order (a later context overrides an earlier one
on a conflicting key) and then overlaid by the stack’s own environment
variables. Manage a context itself (create/update/delete, its own
variables) with gantrycli contexts.
gantrycli stacks contextsgantrycli stacks contexts list
List the contexts a stack references, in application order
gantrycli stacks contexts list [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli stacks contexts replace
Full replacement: pass —context in the order contexts should apply (later overrides earlier on a conflicting key); the stack’s own environment variables always win over any context. Pass —clear with no —context to detach all contexts.
gantrycli stacks contexts replace [flags]Flags:
--clear Detach all contexts from the stack
--context stringArray Context id, in application order (may be repeated)
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli stacks env
Manage a stack’s own environment variables — the ones set directly on
the stack, not the ones it inherits from an attached context. To see the
final merged environment (contexts overlaid by the stack’s own values),
use gantrycli stacks resolved-env.
gantrycli stacks envgantrycli stacks env list
List a stack’s own environment variables
gantrycli stacks env list [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli stacks env replace
Full replacement: the set you pass becomes the stack’s complete list of its own environment variables — any key already set but omitted here is deleted. Pass —clear with no —var/—sensitive-var to wipe them all.
gantrycli stacks env replace [flags]Flags:
--clear Remove all of the stack's own environment variables
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--sensitive-var stringArray Sensitive environment variable as key=value (may be repeated)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)
--var stringArray Environment variable as key=value (may be repeated)gantrycli stacks get
Show a single stack including the latest synced commit
gantrycli stacks get <stack-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli stacks list
List stacks in an org
gantrycli stacks list [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli stacks resolved-env
The merged environment a deploy would actually see: each attached context’s variables (in order, later wins), overlaid by the stack’s own variables (stack always wins). Sensitive values are redacted.
gantrycli stacks resolved-env [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli stacks service-account
Every stack has an implicit default service account used for automated
access (e.g. deploy-time credentials); manage the roles granted to it
with gantrycli stacks service-account role-assignments.
gantrycli stacks service-accountgantrycli stacks service-account get
Show a stack’s default service account
gantrycli stacks service-account get [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli stacks service-account role-assignments
Manage the roles granted to a stack’s default service account
gantrycli stacks service-account role-assignmentsgantrycli stacks service-account role-assignments assign
Grant a role to a stack’s default service account
gantrycli stacks service-account role-assignments assign [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--role-key string Role key to grant (required)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli stacks service-account role-assignments list
List the roles granted to a stack’s default service account
gantrycli stacks service-account role-assignments list [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli stacks service-account role-assignments revoke
Revoke a role assignment from a stack’s default service account
gantrycli stacks service-account role-assignments revoke <assignment-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)
--stack string Stack id (defaults to $GANTRYCD_STACK_ID)gantrycli stacks sync
Force-fetch the latest commit SHA from the SCM and update the stack
gantrycli stacks sync <stack-id> [flags]Flags:
--org string Organization id (defaults to $GANTRYCD_ORG_ID)
--output format Output format: text or json (default text)gantrycli whoami
Print the user the current PAT authenticates as
gantrycli whoami [flags]Flags:
--output format Output format: text or json (default text)