Access commands¶
Common global behavior is documented in the CLI hub. The complete access, MFA, and step-up command contracts follow.
gdsgate ls [--leased]¶
Lists resources the policy lets you view (RBAC-filtered). Output is a
table on stdout:
resource name kind port env lease
edge.svc - tcp - prod -
prod-db prod-db postgres 5432 prod -
test-orders-db test-orders-db postgres 5432 test 14m
web-01 web-01 ssh 22 dev -
| Column | Value |
|---|---|
name |
Name the resource is addressed by, plus aliases. A dash when the id carries _ or . (not a legal name). |
port |
Port a connection goes to: declared in the catalog, else the kind's well-known port. A dash for tcp, mcp, llm, web, web-egress without a declared port. |
lease |
Time left before a resource written inside an auto-scope expires unless renewed. expired: the lease ran out and the row is not swept yet. A dash: declared by an operator, no lease. |
--leased lists only rows that hold a lease. --wide adds serving,
onward auth, native name and labels. --json prints one object per
resource; a field the table shows as a dash is absent.
db ls, kube ls, rdp ls, tcp ls and mcp ls print the same table with
the same flags, filtered to their kinds.
gdsgate request-access <resource> --reason <text> [--action <action>] [--ttl <secs>]¶
Files a JIT access request for <resource> (logged to the audit chain).
Prints the request id.
| Flag | Default | Purpose |
|---|---|---|
--reason <text> |
required | Justification shown to approvers. Required. |
--action <action> |
connect |
Cedar action the elevation is scoped to. connect covers opening a session on any kind of resource. Name an action inside a session (kubeRequest, mcpCallTool) to elevate that action. |
--ttl <secs> |
3600 |
Requested elevation window. |
gdsgate approve <id>¶
Confirm a pending access request as one approver. The required number of distinct approvers comes from the approvals cascade.
gdsgate requests¶
Lists pending and recent access requests with their approval state.
Columns: id, requester, resource, action, state, approvals,
reason. --wide adds expires, the end of the elevation window of an
approved request; a dash while the request is pending. --json prints one
object per request.
gdsgate mfa enroll¶
Starts TOTP enrollment. Prints an otpauth:// URI (scan as a QR code) and the
base32 secret for manual entry. Add it to an authenticator app and activate it
with gdsgate mfa confirm <code>. An unconfirmed factor satisfies no policy.
gdsgate mfa confirm <code>¶
Activates a pending TOTP enrollment with the first code from your app.
gdsgate mfa verify <code>¶
Performs a gateway TOTP step-up: refreshes your step_up_satisfied /
totp_satisfied recency, so a policy that demands a fresh step-up
(Policy → Two MFA channels) admits the next
request. Run it when a call is denied for lack of a fresh gateway step-up. It
does not refresh the IdP-login mfa_satisfied channel.
gdsgate mfa register-passkey¶
Registers a WebAuthn passkey. With [proxy].public_origin
set, it opens the gateway's registration page (https://<public_origin>/mfa/register/...)
and polls until you create the passkey there; the credential is scoped to the
gateway domain. Without it, the dev localhost loopback is used. Requires a
relying party in [mfa.webauthn]. Run once; then
step up with gdsgate step-up <resource>.
gdsgate mfa step-up¶
Performs a WebAuthn step-up (passkey assertion) in the browser and refreshes
your webauthn_satisfied / step_up_satisfied recency. Reusable;
gdsgate step-up <resource> issues a single-use grant.
gdsgate step-up <resource> [--action <action>] [--code <totp>]¶
Issues a one-time step-up grant bound to (you, resource, action). The grant is
spent by the next request the policy admits on it; a request another
rule allows leaves it unspent. Without --code it opens the gateway's
confirmation page (https://<public_origin>/mfa/confirm/..., requires
[proxy].public_origin) and polls until you
complete the passkey there. With --code <totp> it uses TOTP. A deny that
needs a grant names the full command, --action included.
<resource> is a resource id for connect and for llmCall, and an
MCP tool-id (<server>.<tool>) for mcpCallTool. For the six discrete acts it
is the id of the thing being acted on: a session uid (viewRecordings or
killSession), the role a token becomes (issueJoinToken), a
certificate-authority slug (rotateCA), an access-request id (approveRequest)
or a policy-proposal version (approvePolicyEdit). A Kubernetes cluster also
takes --action kubeRequest: the grant is keyed to the cluster, and the policy
must narrow it by request context.
| Flag | Default | Purpose |
|---|---|---|
--action <action> |
derived from the resource's catalogued kind (ssh / database / TCP / web / desktop → connect, mcp → mcpCallTool, llm → llmCall) |
Cedar action the grant applies to: connect, kubeRequest, httpRequest, mcpCallTool, mcpReadResource, mcpGetPrompt, llmCall, viewRecordings, issueJoinToken, killSession, rotateCA, approveRequest, approvePolicyEdit. Required when the resource is not a catalogue entry. kubeRequest spends one grant per apiserver request; the rule pairs its marker with verb, kind, namespace/name and subresource. |
--code <totp> |
none | Issues a TOTP-backed grant. Without it, the command opens a passkey ceremony. |
enroll confirm verify register-passkey step-up