Twingate CLI

Connect, switch accounts, list Resources, and change Client settings from the command line on macOS, Windows, and Linux.

The Twingate CLI is the twingate command. It is installed with the Twingate Client on macOS, Windows, and Linux and controls the same Client as the desktop app. Any change you make with the CLI, such as connecting or switching accounts, also appears in the desktop app.

Use cases

Use the Twingate CLI to:

  • Connect or disconnect the Client from a terminal, SSH session, or script without opening the desktop app.
  • Check connection state, the active network, and the signed-in user, including in a machine-readable format for monitoring scripts.
  • List the Resources you can access and authenticate to a Resource that requires re-authentication.
  • Sync Kubernetes and SSH Resources to the device on demand.
  • Add, switch between, and remove Twingate accounts, including adding a Service Account with a service key.
  • Route internet traffic through an Exit Network.
  • Turn Client settings on or off, such as detailed logs and SSH or Kubernetes Resource sync.
  • Check for and install Client updates.
  • Turn on tab completion for twingate commands in bash, zsh, or PowerShell.
  • Switch a Linux device between TUN mode and HTTP Proxy Mode, for example to run the Client without root in a container or CI job.

Command reference

The table lists every Twingate CLI command. Each command is described in its own section below.

CommandDescription
twingate connect [ACCOUNT]Connect to a Twingate network.
twingate disconnectDisconnect from the current network.
twingate statusShow connection status.
twingate resource listList the Resources you can access.
twingate resource auth <RESOURCE>Authenticate to a Resource.
twingate resource sync [RESOURCE] [--type kube|ssh]Sync Kubernetes and SSH Resources to the device.
twingate account add [NETWORK | FILE]Add an account with a network name or a service key.
twingate account listList configured accounts.
twingate account switch <ACCOUNT>Make another account the active account.
twingate account remove <ACCOUNT>Remove an account.
twingate config collect-detailed-logs [true|false]Read or set detailed (debug-level) log collection.
twingate config share-crash-report [true|false]Read or set crash report sharing.
twingate config enable-local-telemetry [true|false]Read or set local telemetry collection.
twingate config ssh [true|false]Read or set automatic sync of SSH Resources.
twingate config kube [true|false]Read or set automatic sync of Kubernetes Resources.
twingate config tun [true|false]Read or set TUN mode. Linux only.
twingate config http-proxy [IP:PORT|off]Read or set HTTP Proxy Mode and its listen address. Linux only.
twingate exit-network listList available Exit Networks.
twingate exit-network set <name-or-id>Route traffic through an Exit Network.
twingate exit-network offStop routing traffic through an Exit Network.
twingate exit-network statusShow the current Exit Network.
twingate updateCheck for and install Client updates.
twingate completion [SHELL]Show how to turn on shell completion for bash, zsh, or PowerShell.
twingate help [COMMAND]Show help for the CLI or for a command.

Global options

OptionDescription
-h, --helpShow help. Works after any command or subcommand, for example twingate account add --help.
-V, --versionPrint the Client version.

Output formats

Commands that return data (twingate status, twingate resource list, twingate account list, and twingate exit-network list) accept these options:

OptionDescription
-o, --output <FORMAT>Output format. text (default) or json.
-v, --verboseShow additional detail.

Use --output json in scripts. The text format is meant for people to read and can change between versions.

Installation

The Twingate CLI is installed with the Twingate Client. It doesn’t require a separate download.

  • Install the Twingate Client for your platform from the Twingate Client page.
  • Open a new terminal window.
  • Run twingate --version to confirm the CLI is available.
PlatformCLI location
macOS/usr/local/bin/twingate, linked to the CLI inside the Twingate app bundle.
Windows
Linux

Connect and disconnect

twingate connect

Connect the Client to a Twingate network.

twingate connect [ACCOUNT]
ArgumentRequiredDescription
ACCOUNTNoNetwork to connect to, for example acme or acme.twingate.com.

Examples:

# Connect to the active account
twingate connect
# Connect to a specific network
twingate connect acme.twingate.com

If the account requires sign-in, the Client opens your identity provider in a browser.

twingate disconnect

Disconnect the Client from the current network. Twingate Resources and Internet Security features are unavailable until you connect again.

twingate disconnect

Check status

twingate status

Show whether the Client is connected, which network and user are active, and the Client version.

twingate status [--output text|json] [--verbose]

Example text output with --verbose:

Status: Connected
Network: acme.twingate.com
User: user@example.com
Internet Security: Enabled
Exit Network: None
Client Version: 2026.308.30275 | 0.198.0

Example JSON output:

twingate status --output json
{
"client_version": "2026.308.30275 | 0.198.0",
"exit_network": null,
"internet_security": "Enabled",
"network": "acme.twingate.com",
"state": "Connected",
"user": "user@example.com"
}
FieldDescription
stateConnection state, for example Connected.
networkFull name of the connected Twingate network.
userEmail address of the signed-in user.
internet_securityWhether Internet Security features are active.
exit_networkName of the active Exit Network, or null.
client_versionInstalled Client version.

Resources

twingate resource list

List the Resources the signed-in user can access.

twingate resource list [--all] [--output text|json] [--verbose]
OptionDescription
--allInclude background Resources.

Example JSON output:

{
"resources": [
{
"address": "*.internal.example.com",
"aliases": [],
"auth_expires_at": 1794558035,
"auth_status": "Accessible",
"id": "UmVzb3VyY2U6MTIzNDU2Nw==",
"is_favorite": false,
"name": "Internal apps",
"resource_type": "Network"
},
{
"address": "grafana.svc.cluster.local",
"aliases": [
{
"address": "grafana.internal",
"open_url": "http://grafana.internal"
}
],
"auth_expires_at": null,
"auth_status": "Accessible",
"id": "UmVzb3VyY2U6NzY1NDMyMQ==",
"is_favorite": true,
"name": "Grafana",
"resource_type": "WebApp"
}
],
"total": 2
}
FieldDescription
idResource ID.
nameResource name.
addressResource address (DNS name, wildcard, IP address, or CIDR range).
aliasesAlternate addresses for the Resource, each with an open_url when one is available.
resource_typeResource type, for example Network or WebApp.
auth_statusWhether the Resource is accessible or requires authentication, for example Accessible.
auth_expires_atWhen the current authentication expires, as a Unix timestamp in seconds, or null.
is_favoriteWhether the user marked the Resource as a favorite in the Client.
totalNumber of Resources returned.

twingate resource auth

Authenticate to a Resource. Use this when a Security Policy requires you to re-authenticate before you can access a Resource.

twingate resource auth <RESOURCE>
ArgumentRequiredDescription
RESOURCEYesResource to authenticate to. Accepts the Resource name, address, or alias.

Example:

twingate resource auth grafana.internal

twingate resource sync

Sync Kubernetes and SSH Resources to the device once, on demand. Use it to pick up new Resources without waiting for automatic sync, or when automatic sync is turned off with twingate config kube false or twingate config ssh false.

twingate resource sync [RESOURCE] [--type kube|ssh]
ArgumentRequiredDescription
RESOURCENoResource to sync. Accepts the Resource name, address, or alias. Omit it to sync all Kubernetes and SSH Resources.
OptionDescription
--type <KIND>Sync only one type of Resource. kube for Kubernetes Resources, ssh for SSH Resources.

Examples:

# Sync every Kubernetes and SSH Resource
twingate resource sync
# Sync only Kubernetes Resources
twingate resource sync --type kube
# Sync one Resource
twingate resource sync prod-cluster

Accounts

An account is a Twingate network plus the identity signed in to it. The Client can store several accounts, and one account is active at a time.

twingate account add

Add an account.

twingate account add [NETWORK | FILE]
ArgumentRequiredDescription
NETWORKNoNetwork to add. Accepts a slug (acme) or a full network name (acme.twingate.com).
FILENoPath to a Service Account service key file.

If you omit the argument, the CLI reads a service key from standard input.

Examples:

# Add a network and sign in as a user
twingate account add acme
# Add a Service Account from a service key file
twingate account add ./service-key.json
# Add a Service Account from standard input
cat ./service-key.json | twingate account add

twingate account list

List configured accounts.

twingate account list [--output text|json] [--verbose]

Example JSON output:

{
"accounts": [
{
"id": "1a2b",
"is_active": true,
"is_admin": false,
"network_name": "acme.twingate.com",
"network_slug": "acme",
"service_key_id": null,
"user_email": "user@example.com"
}
]
}
FieldDescription
idShort account ID. Use it with twingate account switch, twingate account remove, and twingate connect.
is_activeWhether this is the active account.
is_adminWhether the signed-in user is an admin on the network.
network_nameFull network name.
network_slugNetwork slug.
service_key_idService key ID when the account is a Service Account, otherwise null.
user_emailEmail address of the signed-in user, for user accounts.

twingate account switch

Make another account the active account.

twingate account switch <ACCOUNT>
ArgumentRequiredDescription
ACCOUNTYesAccount to switch to. Accepts a network slug (acme), a full network name (acme.twingate.com), or a short ID from twingate account list.

If more than one account uses the same network, for example two users on acme.twingate.com, use the short ID.

twingate account remove

Remove an account from the Client.

twingate account remove <ACCOUNT>
ArgumentRequiredDescription
ACCOUNTYesAccount to remove. Accepts a network slug, a full network name, or a short ID from twingate account list.

Settings

Each twingate config command reads or sets one Client setting. Run the command without a value to print the current setting. Run it with true or false to change the setting.

# Print the current value
twingate config ssh
# ssh: false
# Change the value
twingate config ssh true
CommandSetting
twingate config collect-detailed-logs [true|false]Collect detailed (debug-level) logs. Turn this on when troubleshooting with Twingate support.
twingate config share-crash-report [true|false]Send crash reports to Twingate.
twingate config enable-local-telemetry [true|false]Collect telemetry locally on the device.
twingate config ssh [true|false]Sync SSH Resources to the device automatically. To sync once, run twingate resource sync --type ssh. See Privileged Access for SSH.
twingate config kube [true|false]Sync Kubernetes Resources to the local kubeconfig automatically. To sync once, run twingate resource sync --type kube. See Kubeconfig Sync.

Linux network modes

On Linux, the Client can send traffic to Twingate through a TUN interface, a local HTTP proxy, or both. TUN mode captures traffic for Resources at the network layer and requires root. HTTP Proxy Mode runs a local HTTP/HTTPS proxy that applications must be configured to use, and doesn’t require root. Userspace Networking covers when to use each mode.

These commands are available only in the Linux CLI.

twingate config tun

Read or set TUN mode.

twingate config tun [true|false]
ArgumentRequiredDescription
true|falseNotrue routes traffic through the TUN interface. false turns TUN mode off. Omit to print the current value.

Example:

twingate config tun false
# tun: false
# Note: tun settings will take effect only after restarting the Twingate connection. Please run "twingate connect" to apply this setting

twingate config http-proxy

Read or set HTTP Proxy Mode and the address the proxy listens on.

twingate config http-proxy [IP:PORT|off]
ArgumentRequiredDescription
IP:PORT|offNoIP:PORT turns on HTTP Proxy Mode and sets the listen address, for example 127.0.0.1:9999. off turns HTTP Proxy Mode off. Omit to print the current value. The command prints (disabled) when HTTP Proxy Mode is off.

Example:

twingate config http-proxy 127.0.0.1:9999
# http-proxy: 127.0.0.1:9999
# Note: http-proxy settings will take effect only after restarting the Twingate connection. Please run "twingate connect" to apply this setting

At least one mode must stay on. To switch from TUN mode to HTTP Proxy Mode only, turn on the proxy before you turn off TUN:

twingate config http-proxy 127.0.0.1:9999
twingate config tun false
twingate connect

Exit Networks

Exit Networks route the device’s internet traffic through a Remote Network. Exit Networks are available on the Enterprise plan.

twingate exit-network list

List the Exit Networks available to you.

twingate exit-network list [--output text|json] [--verbose]

Example JSON output:

{
"exit_networks": [
{
"id": "UmVtb3RlTmV0d29yazoxMjM0NTY=",
"is_selected": false,
"name": "Exit Network - US"
}
],
"selection_expires_at": null,
"total": 1
}
FieldDescription
exit_networks[].idExit Network ID.
exit_networks[].nameExit Network name.
exit_networks[].is_selectedWhether traffic is currently routed through this Exit Network.
selection_expires_atWhen the current selection expires, or null.
totalNumber of Exit Networks returned.

twingate exit-network set

Route internet traffic through an Exit Network.

twingate exit-network set <name-or-id>
ArgumentRequiredDescription
name-or-idYesExit Network name or ID from twingate exit-network list. Quote names that contain spaces.

Example:

twingate exit-network set "Exit Network - US"

twingate exit-network off

Stop routing internet traffic through an Exit Network.

twingate exit-network off

twingate exit-network status

Show the Exit Network in use. Prints No active exit network when none is selected.

twingate exit-network status

Updates

twingate update

Check for a Client update and install it if one is available.

twingate update [--check]
OptionDescription
--checkOnly check whether an update is available. Doesn’t install it.

If the Client is current, the command prints Already up to date.

Shell completion

twingate completion

Print the setup steps for tab completion of twingate commands, subcommands, and options.

twingate completion [SHELL]
ArgumentRequiredDescription
SHELLNoShell to set up: bash, zsh, or powershell. Defaults to the shell running the command.

The command prints setup instructions and doesn’t change any files. Add the printed lines to your shell profile, then open a new shell.

ShellProfile fileLine to add
bash~/.bashrcsource <(COMPLETE=bash twingate)
zsh~/.zshrcautoload -Uz compinit && compinit and source <(COMPLETE=zsh twingate)
PowerShell$PROFILE$env:COMPLETE = "powershell"; twingate | Out-String | Invoke-Expression; Remove-Item Env:\COMPLETE

Common tasks

Connect to a network from a script

twingate connect acme.twingate.com
twingate status --output json

Check that state is Connected in the JSON output before running commands that depend on Twingate Resources.

Switch between two Twingate networks

twingate account list
twingate account switch acme-staging
twingate connect

Set up a headless device with a service key

twingate account add ./service-key.json
twingate connect
twingate resource list --output json

Headless Clients covers creating Service Accounts and service keys.

Collect logs for Twingate support

twingate config collect-detailed-logs true

Reproduce the issue, then follow the steps in troubleshooting to send logs to support. Turn detailed logs off afterward with twingate config collect-detailed-logs false.

Last updated