Skip to content

CLI

Command references by family, grouped by what they are for:

Group Pages
Deploy setup, service, join
Administer administration, sessions, trust, diagnostics
Use client, access, protocols, delegation

This page lists every command with a link to its reference.

Examples use catalog ids such as prod-db; substitute your own resource names. Use resources published in your deployment; the examples do not create them.

One binary, gdsgate on Linux and gdsgate.exe on Windows, runs every service role and every client command, selected by subcommand. Platform differences are noted on each command's page. A global --config <PATH> applies to all commands and overrides the selected or installed configuration for that invocation.

gdsgate [--config <PATH>] <command> [args...]

Output convention:

  • stdout carries data the caller may pipe or capture: ls tables, generated config fragments, byte streams, certificate PEMs.

  • stderr carries status and logs. A client command prints status lines there (→ in progress, ✓ done, # a note):

    ✓ authenticated as alex@acme.io (group: sre)
✓ certificate issued · ttl 5m · db-prod
# connected · session a1f7… · recording

    On a terminal the lines carry glyphs and colour. Off a terminal (a ProxyCommand, a pipe, CI) they are plain ASCII without colour. NO_COLOR also disables colour. proxy-ssh puts only the SSH byte stream on stdout. -q/--quiet silences status lines; failures use ERROR tracing events.

Operational failures, including argument parsing and configuration errors before logging is initialized, use the selected tracing format on stderr. Set GDSGATE_LOG_FORMAT=json for structured error events. Command data, help and version output remain on stdout. Argument errors retain exit code 2; other uncaught command failures retain exit code 1.

Diagnostic logs (tracing events) are filtered with RUST_LOG. A client command defaults to warn; the services default to warn,gdsgate=info. A set RUST_LOG replaces the default:

RUST_LOG=gdsgate_proxy=debug,gdsgate=info,warn gdsgate --config proxy.toml proxy
RUST_LOG=debug gdsgate ssh connect db-prod   # raise a client command's logs for debugging

Configuration selection

gdsgate connect selects the client configuration it writes. To select another existing configuration:

gdsgate contexts use ~/.gdsgate/ha.toml
gdsgate contexts show
gdsgate contexts list
gdsgate resources list
gdsgate authority publication show
gdsgate authority publication set auto
gdsgate authority resources list

Access and administrative RPC commands use the same selection. Rights are checked by Authority using the current identity and policy. Selecting a file preserves stored identities. --config PATH overrides the selection for one invocation. Without a selection, the legacy ~/.gdsgate/config.toml remains the default.

If neither file is available, access commands stop and name connect, contexts use and --config as the ways to select a cluster. They do not contact a default localhost gateway. Offline configuration, setup and completion commands remain available without a selected cluster.

Daemons and local Authority key/store operations use the configuration of their installed role. Setup, join and service installation record completed role paths. A role without configuration refuses to start; multiple configurations require --config PATH. Administrative RPCs use a unique installed Authority only when there is no selected or legacy client configuration. doctor uses a unique installed configuration, otherwise the selected client configuration. With several installed roles, use doctor --role proxy or an explicit configuration path. Reports include the analysed role.

Generated SSH and Kubernetes commands carry an absolute configuration path. contexts use PATH also reloads a running resident and regenerates its managed files. Manually saved command copies retain their original path. Sudo client commands retain the invoking account's selection; a root login uses root's selection. Elevated role discovery reads the machine installation.

Switch a running resident without stopping its process:

gdsgate contexts use ~/.gdsgate/clusters/production/config.toml
gdsgate login
gdsgate status --refresh

A refused reload leaves the previous selection and resident configuration in force. There is one resident control socket per invoking account. status reports the loaded config_path, cluster and reload generation; resources list queries the selected cluster. Reload describes supported changes and the OS settings requiring a restart.

Global flags

Flag Purpose
--config <PATH> TOML configuration for this invocation. The file must exist. Without the flag, commands resolve the selected cluster or installed role. The selection remains unchanged. GDSGATE_* environment overrides apply after the file is loaded.
--as <grant-id> Narrow this session to a delegation grant you own: access is your rights ∩ the grant's capabilities ∩ the session's resource, checked on every operation. After the grant is revoked or expires, the next operation is refused. -L / -R need ssh:forward@<host> and -A needs ssh:agent@<host>; ssh:connect includes neither. See gdsgate delegations create.
--no-remediate On an access denial that step-up or an access request could resolve, report it without offering either. Implied when stdin or stderr is not a terminal.
--step-up-factor <auto\|passkey\|totp> Factor for an inline step-up. Default auto, which prefers the passkey.
--wait When a denial is curable only by a human approval, file the request and block until it is approved, then retry. No effect on a step-up-only denial.
--wait-timeout <secs> How long --wait blocks before giving up. Default 600.
--quiet, -q Silence the client status narration on stderr; failures still print. Command data on stdout is unaffected, and diagnostics remain available through RUST_LOG.
--help, -h Print help for the current command.
--version, -V Print the binary's version and exit.

On a denied ssh, db login, or proxy command at a terminal, gdsgate offers the matching step-up, or files a JIT access request, and retries. See User guide → MFA & step-up. The --no-remediate / --step-up-factor / --wait flags above tune that.

Entity/action paths

Primary paths use entity action. Previous invocations remain aliases with the same permissions and output.

authority
authority agents list
authority agents remove
authority agents set
authority agents switch
authority audit checkpoint-keys export
authority audit verify
authority ca export
authority ca keys prune
authority ca rotate
authority ca seeds wrap
authority epochs activate
authority identities bootstrap
authority keys legacy migrate
authority keys loss accept
authority keys manifest show
authority keys rotation activate
authority keys rotation prepare
authority keys rotation retire
authority keys sync root rotation activate
authority keys sync root rotation cancel
authority keys sync root rotation prepare
authority keys sync root status
authority keys sync root wrap
authority keys sync tokens create
authority nodes import
authority nodes list
authority nodes remove
authority nodes revoke
authority offers list
authority policy proposals approve
authority policy proposals list
authority policy proposals reject
authority profile set
authority resources bind
authority resources list
authority resources members
authority resources remove
authority resources restore
authority resources set
authority resources unbind
authority scopes list
authority scopes remove
authority scopes set
authority store migrate
authority tokens create
authority users forget-name
authority workloads list
authority workloads revoke
ca host-certs learn
ca host-keys learn
completion generate
completion resources list
connector
db list
delegations agent-profiles list
delegations agent-profiles show
delegations create
delegations list
delegations profiles list
delegations renew
delegations revoke
delegations status
identity bootstrap
identity renew
kube list
mcp list
mfa grants create
mfa passkeys register
mfa passkeys verify
mfa totp confirm
mfa totp enroll
mfa totp verify
proxy
rdp list
reload
requests approve
requests create
requests list
resources list
sessions kill
sessions list
sessions watch
setup
ssh config
ssh config show
ssh connect
ssh proxy
tcp list

Service modes

Each entry links to its full reference.

Authority entity/action paths

Primary administrative groups:

  • gdsgate authority identities bootstrap --role admin|provisioner
  • gdsgate authority tokens create
  • gdsgate authority nodes list|import|revoke|remove
  • gdsgate authority resources list|set|remove
  • gdsgate authority offers list
  • gdsgate authority scopes list|set|remove
  • gdsgate authority agents list|set|switch|remove
  • gdsgate authority users forget-name
  • gdsgate authority workloads list|revoke
  • gdsgate authority epochs activate
  • gdsgate authority profile set
  • gdsgate authority store migrate
  • gdsgate authority ca rotate|export|seeds|keys
  • gdsgate authority policy proposals list|approve|reject
  • gdsgate authority keys rotation prepare|activate|retire
  • gdsgate authority keys sync root status|wrap|rotation
  • gdsgate authority audit verify|checkpoint-keys

Arguments and legacy aliases. Old administrative paths keep the same permissions, output and exit codes.

gdsgate authority

Canonical details: administration reference.

--route <auto|gateway|certificate|emergency|store>

Canonical details: administration reference.

--operator <NAME>

Canonical details: administration reference.

gdsgate authority identities bootstrap --role admin --output-dir <DIR> [--ttl <secs>] [--if-missing]

Canonical details: administration reference.

gdsgate authority identities bootstrap --role provisioner --output-dir <DIR> [--token <TOKEN>] [--if-missing]

Canonical details: administration reference.

gdsgate authority tokens create --role <ROLE> [--ttl <secs>]

Canonical details: administration reference.

gdsgate authority ca rotate user-ssh

Canonical details: administration reference.

gdsgate authority ca rotate onward-ssh

Canonical details: administration reference.

gdsgate authority ca rotate host-tls

Canonical details: administration reference.

gdsgate authority ca rotate spiffe

Canonical details: administration reference.

gdsgate authority ca rotate jwt

Canonical details: administration reference.

gdsgate authority nodes list

Canonical details: administration reference.

gdsgate authority offers list

Canonical details: administration reference.

gdsgate authority scopes list

Canonical details: administration reference.

gdsgate authority scopes set <prefix> --node <ID> --kind <KIND> --env <ENV>

Canonical details: administration reference.

gdsgate authority scopes remove <prefix>

Canonical details: administration reference.

gdsgate authority agents list [--node <id>]

Canonical details: administration reference.

gdsgate authority agents set <id> --node <id> --program <path> --can <capability>

Canonical details: administration reference.

gdsgate authority agents switch <id> [--stop]

Canonical details: administration reference.

gdsgate authority agents remove <id>

Canonical details: administration reference.

gdsgate authority nodes revoke <id>

Canonical details: administration reference.

gdsgate authority nodes remove <id>

Canonical details: administration reference.

gdsgate authority users forget-name <subject>

Canonical details: administration reference.

gdsgate authority nodes import --role <ROLE> --cert <PATH>

Canonical details: administration reference.

gdsgate authority workloads list

Canonical details: administration reference.

gdsgate authority workloads revoke <spiffe-id>

Canonical details: administration reference.

gdsgate authority resources list

Canonical details: administration reference.

gdsgate authority resources list --serving

Canonical details: administration reference.

gdsgate authority resources set <id> --kind <KIND>

Canonical details: administration reference.

gdsgate authority resources remove <id>

Canonical details: administration reference.

gdsgate authority epochs activate --epoch <n>

Canonical details: administration reference.

gdsgate authority ca export onward-ssh

Canonical details: administration reference.

gdsgate authority ca export onward-ssh --all

Canonical details: administration reference.

gdsgate authority init --profile <NAME> [--output <PATH>] [--store-url <URL>] [--control-keyring <REFERENCE>] [--audit-keyring <REFERENCE>] [--kms-key <NAME=KIND:COMMAND>] [--if-missing]

Canonical details: administration reference.

gdsgate authority profile set --profile <NAME> --changed-by <NAME>

Canonical details: administration reference.

gdsgate authority init-anchor [--path <PATH>] [--if-missing] (deprecated)

Deprecated; see Deprecated key commands. Canonical details: administration reference.

gdsgate authority init-revocation-key [--path <PATH>] [--if-missing] (deprecated)

Deprecated; see Deprecated key commands. Canonical details: administration reference.

gdsgate authority init-approval-key [--path <PATH>] [--if-missing] (deprecated)

Deprecated; see Deprecated key commands. Canonical details: administration reference.

gdsgate authority init-inventory-key [--path <PATH>] [--if-missing] (deprecated)

Deprecated; see Deprecated key commands. Canonical details: administration reference.

gdsgate authority init-delegation-key [--path <PATH>] [--if-missing] (deprecated)

Deprecated; see Deprecated key commands. Canonical details: administration reference.

gdsgate authority keys legacy migrate

Canonical details: administration reference.

gdsgate authority audit verify [--checkpoint-keys <FILE>] [--keyring <REFERENCE>]

Canonical details: administration reference.

gdsgate authority audit list [filters]

Canonical details: administration reference.

gdsgate authority store migrate [--check]

Canonical details: administration reference.

gdsgate authority policy template

Canonical details: administration reference.

gdsgate authority policy validate [<FILE>] [-o <FILE>] [--rule-ids]

Canonical details: administration reference.

gdsgate authority policy pull [-o <FILE>] [--version <N>]

Canonical details: administration reference.

gdsgate authority policy history [--json]

Canonical details: administration reference.

gdsgate authority policy diff [<A>] [<B>] [--file <PATH>]

Canonical details: administration reference.

gdsgate authority policy revert <N> [--only <LIST>]

Canonical details: administration reference.

gdsgate authority policy review <N> | --pending <N> | --file <PATH>

Canonical details: administration reference.

gdsgate authority policy push <FILE>

Canonical details: administration reference.

gdsgate authority policy edit

Canonical details: administration reference.

gdsgate authority policy proposals list

Canonical details: administration reference.

gdsgate authority policy proposals approve <version>

Canonical details: administration reference.

gdsgate authority policy proposals reject <version>

Canonical details: administration reference.

gdsgate authority recordings list [filters]

Canonical details: administration reference.

gdsgate authority recordings show <session_uid>

Canonical details: administration reference.

gdsgate authority recordings live <session_uid>

Canonical details: administration reference.

gdsgate proxy

Canonical details: service reference.

gdsgate proxy init --domain <name>

Canonical details: service reference.

gdsgate setup prepare --domain <name> --security-profile <profile>

Canonical details: setup reference.

gdsgate setup kubernetes configure <id> --purpose <api|discovery|both>

Configure API access and discovery in the Connector's existing file. See the setup reference.

gdsgate setup change [--public-port <port>] [--serve <spec>]

Canonical details: setup reference.

gdsgate setup restore [--list] [--checkpoint <name>]

Canonical details: setup reference.

gdsgate setup check [--role client]

Canonical details: setup reference.

gdsgate setup apply --bundle <dir>

Canonical details: setup reference.

gdsgate connector

Canonical details: service reference.

gdsgate connector recordings push [--dry-run]

Canonical details: service reference.

gdsgate agent-host

Canonical details: service reference.

gdsgate join <address>

Canonical details: join reference.

gdsgate all

Canonical details: service reference.

gdsgate reload

Re-read the resident configuration, or use --role for a server component. Canonical details: reload and resident settings.

gdsgate contexts use PATH

Selects a configuration and reloads a running resident. See configuration selection and reload.

gdsgate contexts show

Prints the selected configuration path.

gdsgate contexts list [--json]

Lists configurations remembered by connect and contexts use, together with client TOML files found under ~/.gdsgate. * marks the current selection. Duplicate paths are combined; removed files remain in history as missing. The list includes the legacy config.toml when it is the effective selection. Scanning reads TOML structure without evaluating credential commands, excludes server configurations, and descends up to eight directory levels without following directory symlinks. File symlinks are resolved and deduplicated. --json returns path, current, used, discovered and exists per row.

History starts with this version; earlier selections outside the scanned tree cannot be recovered unless they are still selected. Listing preserves the selection, resident and credential cache.

gdsgate doctor

Canonical details: diagnostics reference.

gdsgate config schema

Canonical details: diagnostics reference.

gdsgate config check

Canonical details: diagnostics reference.

gdsgate service install|uninstall <role>

Canonical details: service reference.

gdsgate client-net

Canonical details: service reference.

Previous command names

Previous calls remain available. New scripts can use the primary paths below. Bare requests and delegations continue to list rows. Flags for a bare list cannot be combined with another action; put each action's flags after it.

Previous call Primary path
machine-id identity bootstrap
completion completion generate <shell>
ls resources list
ssh ssh connect
ssh-config ssh config show
proxy-ssh ssh proxy
request-access requests create
approve requests approve
requests requests list
delegate delegations create
delegations delegations list
revoke delegations revoke
delegation status delegations status
delegation renew delegations renew
mfa enroll mfa totp enroll
mfa confirm mfa totp confirm
mfa verify mfa totp verify
mfa register-passkey mfa passkeys register
mfa step-up mfa passkeys verify
step-up mfa grants create
ca learn-host-key ca host-keys learn
ca learn-host-cert ca host-certs learn

Client commands

Canonical details: client reference.

gdsgate connect <host[:port]>

Canonical details: client reference.

gdsgate login [--browser]

Canonical details: client reference.

gdsgate up [--browser] [--foreground]

Canonical details: client reference.

gdsgate down

Canonical details: client reference.

gdsgate status [--json] [--explain] [--refresh]

Canonical details: client reference.

gdsgate completion generate <bash|zsh|fish|powershell>

Canonical details: client reference.

gdsgate identity bootstrap [--token <jwt> | --provision-token <t>]

Canonical details: client reference.

gdsgate delegations create --can <cap>... [--ttl <secs>] [--bind-key <dir> | --exec <prog> [-- <args>...]]

Canonical details: delegation reference.

What a grant carries into an ssh session

Canonical details: delegation reference.

Saved delegations

Canonical details: delegation reference.

Endpoints: what the program is given

Canonical details: delegation reference.

Agent profiles

Canonical details: delegation reference.

--sandbox basic and --sandbox strict

Canonical details: delegation reference.

The difference between them

Canonical details: delegation reference.

Security limitations

Canonical details: delegation reference.

What the audit chain says about the sandbox

Canonical details: delegation reference.

gdsgate delegations list

Canonical details: delegation reference.

gdsgate delegations revoke <id> | --all | --owner <user>

Canonical details: delegation reference.

gdsgate delegations status [--json]

Canonical details: delegation reference.

gdsgate delegations renew [--endpoint <url>]

Canonical details: delegation reference.

gdsgate resources list

Canonical details: access reference.

gdsgate requests create <resource> --reason <text> [--action <action>] [--ttl <secs>]

Canonical details: access reference.

gdsgate requests approve <id>

Canonical details: access reference.

gdsgate requests list

Canonical details: access reference.

gdsgate mfa totp enroll

Canonical details: access reference.

gdsgate mfa totp confirm <code>

Canonical details: access reference.

gdsgate mfa totp verify <code>

Canonical details: access reference.

gdsgate mfa passkeys register

Canonical details: access reference.

gdsgate mfa passkeys verify

Canonical details: access reference.

gdsgate mfa grants create <resource> [--action <action>] [--code <totp>]

Canonical details: access reference.

gdsgate ssh connect <target> [--exec [-- <ssh args>...]]

Canonical details: protocol reference.

gdsgate ssh config show [<host_pattern>]

Canonical details: protocol reference.

gdsgate ssh proxy <resource>

Canonical details: protocol reference.

gdsgate db list

Canonical details: protocol reference.

gdsgate db login <resource>

Canonical details: protocol reference.

gdsgate db proxy <resource> [--listen <addr>]

Canonical details: protocol reference.

gdsgate kube list

Canonical details: protocol reference.

gdsgate kube login <cluster> [--server <url>]

Canonical details: protocol reference.

gdsgate kube credentials <cluster>

Canonical details: protocol reference.

gdsgate kube proxy <cluster> [--listen <addr>]

Canonical details: protocol reference.

gdsgate rdp list

Canonical details: protocol reference.

gdsgate rdp proxy <resource> [--listen <addr>] [--exec]

Canonical details: protocol reference.

gdsgate tcp list

Canonical details: protocol reference.

gdsgate tcp proxy <resource> [--listen <addr>]

Canonical details: protocol reference.

gdsgate mcp list

Canonical details: protocol reference.

gdsgate mcp proxy <resource> [--listen <addr>]

Canonical details: protocol reference.

gdsgate mcp bridge <endpoint>

Canonical details: protocol reference.

gdsgate web proxy <resource> [--listen <addr>]

Canonical details: protocol reference.

gdsgate web trust [--quiet]

Canonical details: protocol reference.

gdsgate ca rotate [--all]

Canonical details: trust reference.

gdsgate ca host-keys learn <target>

Canonical details: trust reference.

gdsgate ca fingerprint [--file <path>]

Canonical details: trust reference.

gdsgate sessions list

Canonical details: session reference.

gdsgate sessions kill [<id>] [--principal <p>] [--resource <r>]

Canonical details: session reference.

gdsgate sessions watch

Canonical details: session reference.

Environment variables

Cluster-configuration overlay

Every GDSGATE_* listed in Configuration → Environment overrides overlays the matching field in the TOML file. An unset variable changes nothing.

Client-side

Variable Purpose
GDSGATE_ID_TOKEN Identity token to present to the cluster (sub becomes the principal). Skips gdsgate login.
GDSGATE_USER Local-dev principal name when no [oidc] is configured. Default dev.
RUST_LOG Tracing filter. A client command defaults to warn; the resident client and the daemons default to warn,gdsgate=info: gdsgate* at INFO, everything else at WARN.

Machine paths

Variable Purpose
GDSGATE_CONFIG_DIR Absolute root for default role configurations and installed-role records. Defaults to /etc/gdsgate on Linux and %ProgramData%\gdsgate on Windows. Empty or relative values use the platform default. Set the same value for setup and the service environment when relocating an installation.

Node bootstrap

Variable Purpose
GDSGATE_ENROLL_TOKEN One-time node-registration token. Consumed by Authority on first start of a Proxy or Connector. Preferred over enroll.token in the file.

Exit codes

A non-zero exit from authority policy validate indicates a policy error suitable for CI gating.

A provisioning script tells the outcomes apart by exit code: created (0), already there (3), failed (1). Output wording may change; do not parse it. Under set -e, allow 3 explicitly:

gdsgate authority init --profile production --output /etc/gdsgate/authority.toml \
    --control-keyring /etc/gdsgate/control.keys --audit-keyring /etc/gdsgate/audit.keys \
    --if-missing || [ $? -eq 3 ]
gdsgate --config authority.toml authority identities bootstrap --role admin \
    --output-dir /var/lib/gdsgate/admin --if-missing || [ $? -eq 3 ]

gdsgate authority publication show reads the Connector enrollment default; gdsgate authority publication set auto|manual changes it under revision control. gdsgate authority resources members/bind/unbind manages explicit serving assignments. See administrative commands.