CLI¶

The source-checked split references are administration, service, join, diagnostics, client, access, delegation, protocols, trust, and operations. This flat route and its existing anchors stay in place while navigation adopts the family pages.

Executable walkthroughs use the shared Quickstart fixtures. A reference transcript may show a catalog id such as prod-db; that is an existing resource name, not a required deployment name. In the split lab, use lab-read or lab-denied from the Quickstart.

One binary, selected by subcommand. The same gdsgate runs every service role and every client operation. 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 narrates itself there in a lean dialect (→ 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 a little colour; off a terminal (a ProxyCommand, a pipe, CI) they fall back to plain ASCII with no colour, and NO_COLOR also disables colour. The proxy-ssh transport puts only the SSH byte stream on stdout, keeping this narration on stderr, so it composes cleanly with native ssh. -q/--quiet silences the narration; failures still print.

Diagnostic logs (tracing events) are a separate channel, filtered with RUST_LOG. A client command defaults to warn, since the narration above is the status surface; the daemons default to warn,gdsgate=info. A set RUST_LOG replaces the default entirely:

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. Optional, but a file named here must exist: a path that is not there fails the command instead of falling back to the defaults. Without the flag a client command reads `~/.gdsgate/config.toml`, the file `gdsgate connect` writes and the one file that may be absent, and falls back to the loopback dev profile when there is none. A service (`authority`, `proxy`, `connector`, `all`) never falls back to that file: a daemon is configured by the file its operator names. `GDSGATE_*` environment overrides apply either way.
`--as <grant-id>`	Narrow this session to a delegation grant you own; access becomes your rights ∩ the grant's capabilities ∩ the resource the session opened on, checked on every operation. Revoking the grant, or letting it expire, refuses the session's next operation. The ssh forwards are words of their own: a grant reaches `-L` / `-R` only through `ssh:forward@<host>` and `-A` only through `ssh:agent@<host>`, neither of which `ssh:connect` carries. See `gdsgate delegate`.
`--no-remediate`	On a curable access denial, report it instead of offering to step up or request access. 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¶

Service entry points are routed to the complete family references. The flat route keeps the historical headings and anchors as compatibility destinations.

`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} [--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 revoke-node <id>`¶

Canonical details: administration reference.

`gdsgate authority delete-node <id>`¶

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 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]`¶

Canonical details: administration reference.

`gdsgate authority init-revocation-key [--path <PATH>] [--if-missing]`¶

Canonical details: administration reference.

`gdsgate authority init-approval-key [--path <PATH>] [--if-missing]`¶

Canonical details: administration reference.

`gdsgate authority init-inventory-key [--path <PATH>] [--if-missing]`¶

Canonical details: administration reference.

`gdsgate authority init-delegation-key [--path <PATH>] [--if-missing]`¶

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>]`¶

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 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 connector`¶

Canonical details: service reference.

`gdsgate join <domain>`¶

Canonical details: join reference.

`gdsgate all`¶

Canonical details: service reference.

`gdsgate doctor`¶

Canonical details: diagnostics 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]`¶

Canonical details: client reference.

`gdsgate completion <bash|zsh|fish>`¶

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 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: operations reference.

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

Canonical details: operations reference.

`gdsgate session watch`¶

Canonical details: operations 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, 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 bootstrap-admin, authority bootstrap-provisioner and the five 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.

3 is a status of its own because provisioning is a reconcile loop, and a script driving one has three outcomes to tell apart: it created the thing (0), it found the thing (3), it failed (1). Output wording is not a contract, and a script that greps for it breaks the day a sentence is reworded. Under set -e the code has to be admitted explicitly:

gdsgate --config authority.toml authority init-anchor \
    --path /var/lib/gdsgate/anchor.key --if-missing || [ $? -eq 3 ]
gdsgate --config authority.toml authority bootstrap-admin \
    --output-dir /var/lib/gdsgate/admin --if-missing || [ $? -eq 3 ]

CLI¶

Global flags¶

Service modes¶

gdsgate authority¶

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

--operator <NAME>¶

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

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

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

gdsgate authority rotate-ca¶

gdsgate authority rotate-onward-ca¶

gdsgate authority rotate-host-tls-ca¶

gdsgate authority rotate-spiffe-ca¶

gdsgate authority rotate-jwt-ca¶

gdsgate authority list-nodes¶

gdsgate authority list-offered¶

gdsgate authority revoke-node <id>¶

gdsgate authority delete-node <id>¶

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

gdsgate authority list-workloads¶

gdsgate authority revoke-workload <spiffe-id>¶

gdsgate authority list-resources¶

gdsgate authority list-serving¶

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

gdsgate authority remove-resource <id>¶

gdsgate authority onward-ca-pub¶

gdsgate authority onward-ca-pubs¶

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

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

gdsgate authority init-anchor [--path <PATH>] [--if-missing]¶

gdsgate authority init-revocation-key [--path <PATH>] [--if-missing]¶

gdsgate authority init-approval-key [--path <PATH>] [--if-missing]¶

gdsgate authority init-inventory-key [--path <PATH>] [--if-missing]¶

gdsgate authority init-delegation-key [--path <PATH>] [--if-missing]¶

gdsgate authority keys migrate-legacy¶

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

gdsgate authority audit list [filters]¶

gdsgate authority migrate [--check]¶

gdsgate authority policy template¶

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

gdsgate authority policy pull [-o <FILE>]¶

gdsgate authority policy push <FILE>¶

gdsgate authority policy edit¶

gdsgate authority policy pending-edits¶

gdsgate authority policy approve-edit <version>¶

gdsgate authority recordings list [filters]¶

gdsgate authority recordings show <session_uid>¶

gdsgate authority recordings live <session_uid>¶

gdsgate proxy¶

gdsgate connector¶

gdsgate join <domain>¶

gdsgate all¶

gdsgate doctor¶

Client commands¶

gdsgate connect <host[:port]>¶

gdsgate login [--browser]¶

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

gdsgate down¶

gdsgate status [--json] [--explain]¶

gdsgate completion <bash|zsh|fish>¶

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

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

What a grant carries into an ssh session¶

Saved delegations¶

Endpoints: what the program is given¶

Agent profiles¶

--sandbox basic and --sandbox strict¶

The difference between them¶

Security limitations¶

What the audit chain says about the sandbox¶

gdsgate delegations¶

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

gdsgate delegation status [--json]¶

gdsgate delegation renew [--endpoint <url>]¶

gdsgate ls¶

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

gdsgate approve <id>¶

gdsgate requests¶

gdsgate mfa enroll¶

gdsgate mfa confirm <code>¶

`gdsgate authority`¶

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

`--operator <NAME>`¶

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

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

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

`gdsgate authority rotate-ca`¶

`gdsgate authority rotate-onward-ca`¶

`gdsgate authority rotate-host-tls-ca`¶

`gdsgate authority rotate-spiffe-ca`¶

`gdsgate authority rotate-jwt-ca`¶

`gdsgate authority list-nodes`¶

`gdsgate authority list-offered`¶

`gdsgate authority revoke-node <id>`¶

`gdsgate authority delete-node <id>`¶

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

`gdsgate authority list-workloads`¶

`gdsgate authority revoke-workload <spiffe-id>`¶

`gdsgate authority list-resources`¶

`gdsgate authority list-serving`¶

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

`gdsgate authority remove-resource <id>`¶

`gdsgate authority onward-ca-pub`¶

`gdsgate authority onward-ca-pubs`¶

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

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

`gdsgate authority init-anchor [--path <PATH>] [--if-missing]`¶

`gdsgate authority init-revocation-key [--path <PATH>] [--if-missing]`¶

`gdsgate authority init-approval-key [--path <PATH>] [--if-missing]`¶

`gdsgate authority init-inventory-key [--path <PATH>] [--if-missing]`¶

`gdsgate authority init-delegation-key [--path <PATH>] [--if-missing]`¶

`gdsgate authority keys migrate-legacy`¶

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

`gdsgate authority audit list [filters]`¶

`gdsgate authority migrate [--check]`¶

`gdsgate authority policy template`¶

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

`gdsgate authority policy pull [-o <FILE>]`¶

`gdsgate authority policy push <FILE>`¶

`gdsgate authority policy edit`¶

`gdsgate authority policy pending-edits`¶

`gdsgate authority policy approve-edit <version>`¶

`gdsgate authority recordings list [filters]`¶

`gdsgate authority recordings show <session_uid>`¶

`gdsgate authority recordings live <session_uid>`¶

`gdsgate proxy`¶

`gdsgate connector`¶

`gdsgate join <domain>`¶

`gdsgate all`¶

`gdsgate doctor`¶

`gdsgate connect <host[:port]>`¶

`gdsgate login [--browser]`¶

`gdsgate up [--browser] [--foreground]`¶

`gdsgate down`¶

`gdsgate status [--json] [--explain]`¶

`gdsgate completion <bash|zsh|fish>`¶

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

`gdsgate delegate --can <cap>... [--ttl <secs>] [--bind-key <dir> | --exec <prog> [-- <args>...]]`¶

`--sandbox basic` and `--sandbox strict`¶

`gdsgate delegations`¶

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

`gdsgate delegation status [--json]`¶

`gdsgate delegation renew [--endpoint <url>]`¶

`gdsgate ls`¶

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

`gdsgate approve <id>`¶

`gdsgate requests`¶

`gdsgate mfa enroll`¶

`gdsgate mfa confirm <code>`¶

`gdsgate mfa verify <code>`¶

`gdsgate mfa register-passkey`¶

`gdsgate mfa step-up`¶

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

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

`gdsgate ssh-config [<host_pattern>]`¶

`gdsgate proxy-ssh <resource>`¶

`gdsgate db ls`¶

`gdsgate db login <resource>`¶

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

`gdsgate kube ls`¶