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.
Output convention:
- stdout carries data the caller may pipe or capture:
lstables, 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… · recordingOn a terminal the lines carry glyphs and colour. Off a terminal (a
ProxyCommand, a pipe, CI) they are plain ASCII without colour.NO_COLORalso disables colour.proxy-sshputs only the SSH byte stream on stdout.-q/--quietsilences 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 doctorfound a failing check,config checkfound warnings and no error,authority verify-auditfound the audit chain broken, orjoinwas given arguments that do not describe an installation. -
3: nothing to do, where a run with--if-missingfound what it was asked to create and changed nothing. Onlyauthority init,authority bootstrap-admin,authority bootstrap-provisionerand the five deprecatedauthority 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 ]