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 loopback dev defaults.

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, ✗ a failure):

    ✓ 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 still print.

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 db-prod   # raise a client command's logs for debugging

Global flags

Flag Purpose
--config <PATH> Path to the TOML cluster-configuration file. A file named here must exist; a missing file fails the command. Without the flag a client command reads ~/.gdsgate/config.toml (%USERPROFILE%\.gdsgate\config.toml on Windows), the file gdsgate connect writes, and uses the loopback dev profile when it is absent. A service (authority, proxy, connector, all) does not read that file. GDSGATE_* environment overrides apply either way.
--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 delegate.
--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.

Service modes

Each entry links to its full reference.

gdsgate authority

Canonical details: administration reference.

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

Canonical details: administration reference.

--operator <NAME>

Canonical details: administration reference.

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

Canonical details: administration reference.

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

Canonical details: administration reference.

gdsgate authority create-token --role {proxy|connector|admin|workload|provisioner|agent-host} [--ttl <secs>]

Canonical details: administration reference.

gdsgate authority rotate-ca

Canonical details: administration reference.

gdsgate authority rotate-onward-ca

Canonical details: administration reference.

gdsgate authority rotate-host-tls-ca

Canonical details: administration reference.

gdsgate authority rotate-spiffe-ca

Canonical details: administration reference.

gdsgate authority rotate-jwt-ca

Canonical details: administration reference.

gdsgate authority list-nodes

Canonical details: administration reference.

gdsgate authority list-offered

Canonical details: administration reference.

gdsgate authority list-scopes

Canonical details: administration reference.

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

Canonical details: administration reference.

gdsgate authority remove-scope <prefix>

Canonical details: administration reference.

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

Canonical details: administration reference.

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

Canonical details: administration reference.

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

Canonical details: administration reference.

gdsgate authority remove-agent <id>

Canonical details: administration reference.

gdsgate authority revoke-node <id>

Canonical details: administration reference.

gdsgate authority delete-node <id>

Canonical details: administration reference.

gdsgate authority forget-user <subject>

Canonical details: administration reference.

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

Canonical details: administration reference.

gdsgate authority list-workloads

Canonical details: administration reference.

gdsgate authority revoke-workload <spiffe-id>

Canonical details: administration reference.

gdsgate authority list-resources

Canonical details: administration reference.

gdsgate authority list-serving

Canonical details: administration reference.

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

Canonical details: administration reference.

gdsgate authority remove-resource <id>

Canonical details: administration reference.

gdsgate authority activate --epoch <n>

Canonical details: administration reference.

gdsgate authority onward-ca-pub

Canonical details: administration reference.

gdsgate authority onward-ca-pubs

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 set-profile --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 migrate-legacy

Canonical details: administration reference.

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

Canonical details: administration reference.

gdsgate authority audit list [filters]

Canonical details: administration reference.

gdsgate authority 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 pending-edits

Canonical details: administration reference.

gdsgate authority policy approve-edit <version>

Canonical details: administration reference.

gdsgate authority policy reject-edit <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 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 <domain>

Canonical details: join reference.

gdsgate all

Canonical details: service reference.

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.

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 <bash|zsh|fish|powershell>

Canonical details: client reference.

gdsgate machine-id [--token <jwt> | --provision-token <t> | --renew]

Canonical details: client reference.

gdsgate delegate --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

Canonical details: delegation reference.

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

Canonical details: delegation reference.

gdsgate delegation status [--json]

Canonical details: delegation reference.

gdsgate delegation renew [--endpoint <url>]

Canonical details: delegation reference.

gdsgate ls

Canonical details: access reference.

gdsgate request-access <resource> --reason <text> [--action <action>] [--ttl <secs>]

Canonical details: access reference.

gdsgate approve <id>

Canonical details: access reference.

gdsgate requests

Canonical details: access reference.

gdsgate mfa enroll

Canonical details: access reference.

gdsgate mfa confirm <code>

Canonical details: access reference.

gdsgate mfa verify <code>

Canonical details: access reference.

gdsgate mfa register-passkey

Canonical details: access reference.

gdsgate mfa step-up

Canonical details: access reference.

gdsgate step-up <resource> [--action <action>] [--code <totp>]

Canonical details: access reference.

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

Canonical details: protocol reference.

gdsgate ssh-config [<host_pattern>]

Canonical details: protocol reference.

gdsgate proxy-ssh <resource>

Canonical details: protocol reference.

gdsgate db ls

Canonical details: protocol reference.

gdsgate db login <resource>

Canonical details: protocol reference.

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

Canonical details: protocol reference.

gdsgate kube ls

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 ls

Canonical details: protocol reference.

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

Canonical details: protocol reference.

gdsgate tcp ls

Canonical details: protocol reference.

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

Canonical details: protocol reference.

gdsgate mcp ls

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 learn-host-key <target>

Canonical details: trust reference.

gdsgate ca fingerprint [--file <path>]

Canonical details: trust reference.

gdsgate session list

Canonical details: session reference.

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

Canonical details: session reference.

gdsgate session 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.

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

  • 0: command succeeded.
  • 1: generic failure, with the error logged to stderr.
  • 2: gdsgate doctor found a failing check, config check found warnings and no error, authority verify-audit found the audit chain broken, or join was given arguments that do not describe an installation.

  • 3: nothing to do, where a run with --if-missing found what it was asked to create and changed nothing. Only authority init, authority bootstrap-admin, authority bootstrap-provisioner and the five deprecated authority init-* commands produce it, and only when that flag is passed.

  • 101: Rust panic, an unrecoverable internal error worth reporting.

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 bootstrap-admin \
    --output-dir /var/lib/gdsgate/admin --if-missing || [ $? -eq 3 ]