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.
Classic Linux CLI
This page covers the CLI included with the current Twingate Client on macOS, Windows, and Linux. It replaces the classic Linux CLI commands twingate setup, twingate start, twingate stop, and twingate resources. The Linux Client page documents the classic commands.
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
twingatecommands 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.
| Command | Description |
|---|---|
twingate connect [ACCOUNT] | Connect to a Twingate network. |
twingate disconnect | Disconnect from the current network. |
twingate status | Show connection status. |
twingate resource list | List 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 list | List 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 list | List available Exit Networks. |
twingate exit-network set <name-or-id> | Route traffic through an Exit Network. |
twingate exit-network off | Stop routing traffic through an Exit Network. |
twingate exit-network status | Show the current Exit Network. |
twingate update | Check 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
| Option | Description |
|---|---|
-h, --help | Show help. Works after any command or subcommand, for example twingate account add --help. |
-V, --version | Print 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:
| Option | Description |
|---|---|
-o, --output <FORMAT> | Output format. text (default) or json. |
-v, --verbose | Show 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 --versionto confirm the CLI is available.
| Platform | CLI 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]| Argument | Required | Description |
|---|---|---|
ACCOUNT | No | Network to connect to, for example acme or acme.twingate.com. |
Examples:
# Connect to the active accounttwingate connect
# Connect to a specific networktwingate connect acme.twingate.comIf 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 disconnectCheck 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: ConnectedNetwork: acme.twingate.comUser: user@example.comInternet Security: EnabledExit Network: NoneClient Version: 2026.308.30275 | 0.198.0Example 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"}| Field | Description |
|---|---|
state | Connection state, for example Connected. |
network | Full name of the connected Twingate network. |
user | Email address of the signed-in user. |
internet_security | Whether Internet Security features are active. |
exit_network | Name of the active Exit Network, or null. |
client_version | Installed Client version. |
Resources
twingate resource list
List the Resources the signed-in user can access.
twingate resource list [--all] [--output text|json] [--verbose]| Option | Description |
|---|---|
--all | Include 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}| Field | Description |
|---|---|
id | Resource ID. |
name | Resource name. |
address | Resource address (DNS name, wildcard, IP address, or CIDR range). |
aliases | Alternate addresses for the Resource, each with an open_url when one is available. |
resource_type | Resource type, for example Network or WebApp. |
auth_status | Whether the Resource is accessible or requires authentication, for example Accessible. |
auth_expires_at | When the current authentication expires, as a Unix timestamp in seconds, or null. |
is_favorite | Whether the user marked the Resource as a favorite in the Client. |
total | Number 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>| Argument | Required | Description |
|---|---|---|
RESOURCE | Yes | Resource to authenticate to. Accepts the Resource name, address, or alias. |
Example:
twingate resource auth grafana.internaltwingate 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]| Argument | Required | Description |
|---|---|---|
RESOURCE | No | Resource to sync. Accepts the Resource name, address, or alias. Omit it to sync all Kubernetes and SSH Resources. |
| Option | Description |
|---|---|
--type <KIND> | Sync only one type of Resource. kube for Kubernetes Resources, ssh for SSH Resources. |
Examples:
# Sync every Kubernetes and SSH Resourcetwingate resource sync
# Sync only Kubernetes Resourcestwingate resource sync --type kube
# Sync one Resourcetwingate resource sync prod-clusterAccounts
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]| Argument | Required | Description |
|---|---|---|
NETWORK | No | Network to add. Accepts a slug (acme) or a full network name (acme.twingate.com). |
FILE | No | Path 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 usertwingate account add acme
# Add a Service Account from a service key filetwingate account add ./service-key.json
# Add a Service Account from standard inputcat ./service-key.json | twingate account addService keys
A service key grants access to every Resource assigned to its Service Account. Store service keys in a secrets manager and don’t commit them to source control.
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" } ]}| Field | Description |
|---|---|
id | Short account ID. Use it with twingate account switch, twingate account remove, and twingate connect. |
is_active | Whether this is the active account. |
is_admin | Whether the signed-in user is an admin on the network. |
network_name | Full network name. |
network_slug | Network slug. |
service_key_id | Service key ID when the account is a Service Account, otherwise null. |
user_email | Email address of the signed-in user, for user accounts. |
twingate account switch
Make another account the active account.
twingate account switch <ACCOUNT>| Argument | Required | Description |
|---|---|---|
ACCOUNT | Yes | Account 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>| Argument | Required | Description |
|---|---|---|
ACCOUNT | Yes | Account 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 valuetwingate config ssh# ssh: false
# Change the valuetwingate config ssh true| Command | Setting |
|---|---|
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.
Reconnect to apply changes
Changes to tun and http-proxy take effect the next time the Client connects. Run twingate connect after changing either setting.
twingate config tun
Read or set TUN mode.
twingate config tun [true|false]| Argument | Required | Description |
|---|---|---|
true|false | No | true 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 settingtwingate config http-proxy
Read or set HTTP Proxy Mode and the address the proxy listens on.
twingate config http-proxy [IP:PORT|off]| Argument | Required | Description |
|---|---|---|
IP:PORT|off | No | IP: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 settingListen address
A proxy listening on 0.0.0.0 accepts connections from any host that can reach the device. Use 127.0.0.1 unless other hosts, such as containers on the same host, need to use the proxy.
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:9999twingate config tun falsetwingate connectExit 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}| Field | Description |
|---|---|
exit_networks[].id | Exit Network ID. |
exit_networks[].name | Exit Network name. |
exit_networks[].is_selected | Whether traffic is currently routed through this Exit Network. |
selection_expires_at | When the current selection expires, or null. |
total | Number of Exit Networks returned. |
twingate exit-network set
Route internet traffic through an Exit Network.
twingate exit-network set <name-or-id>| Argument | Required | Description |
|---|---|---|
name-or-id | Yes | Exit 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 offtwingate exit-network status
Show the Exit Network in use. Prints No active exit network when none is selected.
twingate exit-network statusUpdates
twingate update
Check for a Client update and install it if one is available.
twingate update [--check]| Option | Description |
|---|---|
--check | Only 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]| Argument | Required | Description |
|---|---|---|
SHELL | No | Shell 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.
| Shell | Profile file | Line to add |
|---|---|---|
| bash | ~/.bashrc | source <(COMPLETE=bash twingate) |
| zsh | ~/.zshrc | autoload -Uz compinit && compinit and source <(COMPLETE=zsh twingate) |
| PowerShell | $PROFILE | $env:COMPLETE = "powershell"; twingate | Out-String | Invoke-Expression; Remove-Item Env:\COMPLETE |
PowerShell version
Shell completion requires PowerShell 7 or later.
Common tasks
Connect to a network from a script
twingate connect acme.twingate.comtwingate status --output jsonCheck that state is Connected in the JSON output before running commands that depend on Twingate Resources.
Switch between two Twingate networks
twingate account listtwingate account switch acme-stagingtwingate connectSet up a headless device with a service key
twingate account add ./service-key.jsontwingate connecttwingate resource list --output jsonHeadless Clients covers creating Service Accounts and service keys.
Collect logs for Twingate support
twingate config collect-detailed-logs trueReproduce 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