Wardengate

Reference

CLI reference (wgctl)

wgctl is the administrative and developer CLI for Wardengate. It wraps the same REST surface the admin console uses, so anything you can do in the UI you can script from a terminal, a Makefile, or a CI pipeline. This page lists every command group with representative invocations; run wgctl <group> --help for the authoritative flag set on your installed version.

Install

The shell installer detects your OS and architecture and drops a single static binary into /usr/local/bin. It is safe to re-run for upgrades.

curl -sSL https://dl.wardengate.io/wgctl/install.sh | sh

macOS (Homebrew)

brew install wardengate/tap/wgctl

Windows (winget)

winget install Wardengate.wgctl

Verified checksums

Every release is published with a checksums.txt file and a cosign signature. For regulated environments, pin a version and verify the archive before installing:

curl -sSLO https://dl.wardengate.io/wgctl/1.6.2/wgctl_linux_amd64.tar.gz
curl -sSLO https://dl.wardengate.io/wgctl/1.6.2/wgctl_1.6.2_checksums.txt
sha256sum --check --ignore-missing wgctl_1.6.2_checksums.txt
tar -xzf wgctl_linux_amd64.tar.gz
sudo install wgctl /usr/local/bin/wgctl

Configuration

wgctl reads its configuration from ~/.wgctl/config.yaml (or the path in WGCTL_CONFIG). Refresh tokens are not stored in the config file — they live in the OS keyring (Keychain on macOS, Secret Service on Linux, Credential Manager on Windows) and are referenced by a token-ref entry.

current-context: prod
contexts:
  prod:
    server: https://wardengate.example.com
    token-ref: keyring:wgctl/prod
    organization: acme
  staging:
    server: https://wg.staging.example.com
    token-ref: keyring:wgctl/staging
    organization: acme-staging

Login

The first sign-in prompts for your server URL and opens a browser for SSO. The refresh token that comes back is written to the keyring and the active context is set for you.

wgctl login --server https://wardengate.example.com
# opens a browser for SSO, stores the refresh token in the OS keyring

wgctl login --server https://wardengate.example.com --token $WG_TOKEN
# non-interactive login for CI agents and scripts

Multiple contexts

A context bundles a server, a token, and an organization. Keep one per environment — flipping between prod and staging is a single command and avoids the accidental wrong-cluster problem.

wgctl context list
wgctl context use staging
wgctl context current

Global flags

These flags work on every command and override the current context for a single invocation.

--context <name>       override current context for this invocation
--server <url>         override the server URL
--org <slug>           scope the command to an organization
-o, --output <format>  json, yaml, table, wide (default: table)
--no-color             disable ANSI color in terminal output
-q, --quiet            suppress non-essential output
-v, --verbose          enable debug logging (repeat for trace)
--timeout <duration>   per-request timeout (default 30s)

session

Inspect, tail, terminate, and replay brokered sessions. Sessions themselves are started by users connecting through the gateway — the CLI never initiates a session, only observes and controls the in-flight ones.

  • session list — filter by user, target, state, time range.
  • session watch — live-tail a session's event stream.
  • session terminate — cut an active session with a reason.
  • session replay — download a recording as an asciicast or MP4.
wgctl session list --state active --user avery@example.com
wgctl session watch ses_01HE6W...
wgctl session terminate ses_01HE6W... --reason "out-of-window access"
wgctl session replay ses_01HE6W... --out session.cast

target

A target is anything Wardengate brokers to: a host, a database, a Kubernetes cluster, a web application. Every target carries a protocol, an address, and zero or more accounts.

  • target create — register a new target.
  • target list — filter by protocol, tag, health state.
  • target describe — show full detail including attached accounts and policies.
  • target delete — remove a target (requires confirmation).
wgctl target create \
  --name web-01.prod \
  --protocol ssh \
  --address 10.10.4.20:22 \
  --account deploy:vault/ssh/deploy-prod \
  --tag env=prod --tag role=web

wgctl target list --tag env=prod
wgctl target describe web-01.prod
wgctl target delete web-01.prod --confirm

policy

Apply, inspect, and simulate access policies. Storing policy manifests in git and running wgctl policy apply from CI is the recommended workflow for any team larger than one.

  • policy apply — upsert one or many policies from a file or directory.
  • policy list — filter by principal, target, or tag.
  • policy simulate — answer "could user X reach target Y right now?" with a full decision trace.
  • policy diff — compare a local manifest against the server copy.
wgctl policy apply -f prod-ssh-read.yaml
wgctl policy list --principal group:sre
wgctl policy simulate \
  --user avery@example.com \
  --target web-01.prod \
  --protocol ssh \
  --account deploy

account

An account is a privileged credential attached to a target — a Linux user, a Windows service account, a database role. Wardengate brokers connections using these accounts so end-users never see the credential material.

  • account create — register an account backed by a vault reference or a stored secret.
  • account rotate — trigger immediate credential rotation.
  • account list — per-target or global inventory.
wgctl account create \
  --target web-01.prod \
  --name deploy \
  --credential-ref vault/ssh/deploy-prod

wgctl account rotate deploy --target web-01.prod
wgctl account list --target web-01.prod

role

Roles govern what operators can do inside Wardengate itself — who can author policy, who can view recordings, who can approve. Roles are scoped per organization.

  • role list — built-in and custom roles.
  • role create — compose a role from permission strings.
  • role grant / revoke — attach or detach a role from a user or group.
wgctl role list
wgctl role create \
  --name policy-author \
  --permission policy:read \
  --permission policy:write

wgctl role grant policy-author --group sre-leads
wgctl role revoke policy-author --user avery@example.com

org

Organizations are the top-level tenancy unit. A single Wardengate install can host many orgs, each with its own identity providers, targets, policies, and recordings.

  • org list / describe — inventory and settings.
  • org create — bootstrap a new tenant (super-admin only).
  • org members — list members and their roles.
wgctl org list
wgctl org create --name acme --display "Acme Corporation"
wgctl org describe acme
wgctl org members --org acme --role admin

mfa

Manage multi-factor enrolment, step-up policies, and per-user methods. The CLI is the easiest way to reset a locked user or audit who has a weak factor.

  • mfa policy apply — set when step-up is required.
  • mfa enroll — enrol a new factor for the current user.
  • mfa methods — list enrolled factors for a user.
  • mfa reset — clear a factor (requires admin permission).
wgctl mfa policy apply -f step-up.yaml
wgctl mfa enroll --method webauthn
wgctl mfa methods --user avery@example.com
wgctl mfa reset --user avery@example.com --method totp

approval

Drive approval-gated access from the terminal. Useful for on-call approvers who live in tmux and do not want to leave for a browser every time a request lands.

  • approval list — filter by requester, target, or state.
  • approval grant / deny — act on a pending request with an audit note.
  • approval watch — block until a request reaches a terminal state.
wgctl approval list --state pending
wgctl approval grant apr_01HE6W... --note "change ticket CHG-4421"
wgctl approval deny apr_01HE6W... --reason "outside change window"
wgctl approval watch apr_01HE6W...

backup

Orchestrate control-plane backups and validate restores. Backups cover policy, identity, and audit metadata — recordings are covered by bucket replication, not by this command.

  • backup create — snapshot Postgres and the vault to an object store.
  • backup list — recent backups and their retention status.
  • backup verify — check checksums and readability.
  • backup restore — restore into the current cluster or a scratch target.
wgctl backup create --destination s3://wg-backups/2026-04-20/
wgctl backup list
wgctl backup verify bk_01HE6W...
wgctl backup restore bk_01HE6W... --into scratch-cluster --dry-run

system

Health checks, version information, and diagnostics for support.system diagnostics collect bundles logs and anonymised configuration into a single archive you can hand to support without leaking secrets.

wgctl system health
wgctl system version
wgctl system verify
wgctl system diagnostics collect --out wg-diag-$(date +%s).tgz

Shell completion

wgctl completion emits completion scripts for bash, zsh, fish, and PowerShell. The scripts complete against live server data — target names, policy names, session IDs — so tab completion stays accurate as your inventory changes.

# Bash (current session)
source <(wgctl completion bash)

# Zsh (install once)
wgctl completion zsh > "${fpath[1]}/_wgctl"

# Fish
wgctl completion fish | source

# PowerShell
wgctl completion powershell | Out-String | Invoke-Expression

Related

  • API reference — the HTTP surface the CLI calls under the hood.
  • SDKs — if you want the same operations from code instead of a shell.
  • Terraform provider — for declarative, reviewable changes to policy and targets.