Tailscale CLI
CLI for the Tailscale API v2 β manage devices, ACLs, DNS, keys, users, webhooks & more from the terminal. Includes MCP server (39 tools) for Claude Code / AI assistants.
Ask AI about Tailscale CLI
Powered by Claude Β· Grounded in docs
I know everything about Tailscale CLI. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
tailscale-cli
CLI for the Tailscale API v2 β manage your tailnet from the terminal.
Features
- 85 endpoints covered: devices, ACL, DNS, keys, users, webhooks, services, and more
- Secure token storage: stored in your system's credential manager (macOS Keychain, Windows Credential Manager, Linux Secret Service)
- Multi-context: manage multiple Tailscale accounts
- Flexible output: table, JSON, YAML, CSV
- Cross-platform: macOS, Linux, Windows (amd64 and arm64)
- MCP integration: 39 tools for Claude Code, VS Code, JetBrains
Prerequisites
- A Tailscale account with admin console access
- A Tailscale API token (created from Settings > Keys)
Installation
Method 1: Download the binary (recommended)
Go to the Releases page and download the archive for your platform.
Or with a single command:
macOS (Apple Silicon β M1/M2/M3/M4):
curl -sL https://github.com/dimer47/tailscale-cli/releases/latest/download/tailscale-cli_darwin_arm64.tar.gz | tar xz
sudo mv tailscale-cli /usr/local/bin/
macOS (Intel):
curl -sL https://github.com/dimer47/tailscale-cli/releases/latest/download/tailscale-cli_darwin_amd64.tar.gz | tar xz
sudo mv tailscale-cli /usr/local/bin/
Linux (amd64):
curl -sL https://github.com/dimer47/tailscale-cli/releases/latest/download/tailscale-cli_linux_amd64.tar.gz | tar xz
sudo mv tailscale-cli /usr/local/bin/
Linux (arm64 β Raspberry Pi, etc.):
curl -sL https://github.com/dimer47/tailscale-cli/releases/latest/download/tailscale-cli_linux_arm64.tar.gz | tar xz
sudo mv tailscale-cli /usr/local/bin/
Windows:
Download tailscale-cli_windows_amd64.zip from the Releases page, extract and add the folder to your PATH.
Method 2: From source (requires Go 1.21+)
go install github.com/dimer47/tailscale-cli@latest
The binary will be installed in $GOPATH/bin/ (usually ~/go/bin/). Make sure this directory is in your PATH.
Method 3: Build locally
git clone https://github.com/dimer47/tailscale-cli.git
cd tailscale-cli
go build -o tailscale-cli .
./tailscale-cli version
Verify installation
tailscale-cli version
# tailscale-cli version 0.2.0 (commit: abc1234, built: 2026-04-30T22:10:36Z)
Updating
The CLI automatically checks for new versions at startup and notifies you when an update is available.
# Update to the latest version
tailscale-cli self-update
# Check for updates without installing
tailscale-cli self-update --check
The update is downloaded from GitHub Releases and replaces the current binary in place. If the binary is in a protected directory (e.g. /usr/local/bin/), sudo will be requested automatically.
Quick Start
1. Get a Tailscale API token
- Log in to the Tailscale admin console
- Go to Settings > Keys
- Click Generate API access token
- Choose the expiration duration (1 to 90 days)
- Copy the token (
tskey-api-xxxxx...)
2. Configure the CLI
tailscale-cli auth login
Answer the 3 prompts:
Context name (default): Enter # Press Enter for "default"
Tailscale API token: tskey-api-xxxxx # Paste your token
Tailnet (- for default): Enter # Press Enter
The token is stored in your system credential manager (macOS Keychain, Windows Credential Manager, or Linux Secret Service) β encrypted, never written in plain text on disk.
3. Test it
# List your devices
tailscale-cli device list
# JSON output
tailscale-cli device list --json
# View your tailnet settings
tailscale-cli settings get
Configuration
Token resolution priority
| Priority | Source | Use case |
|---|---|---|
| 1 | Flag --api-token | One-off tests |
| 2 | Env var TSCLI_API_TOKEN | CI/CD, scripts |
| 3 | System credential manager | Daily use (via auth login) |
| 4 | Config file (legacy) | Migration from older versions |
Multi-context (multiple Tailscale accounts)
# Configure a "work" context
tailscale-cli auth login
# -> Enter "work" as context name
# Configure a "personal" context
tailscale-cli auth login
# -> Enter "personal" as context name
# List all contexts (* = active)
tailscale-cli auth list
# * work (tailnet: mycompany.com, token in credential store)
# personal (tailnet: -, token in credential store)
# Switch context
tailscale-cli auth switch personal
# Use a context for a single command
tailscale-cli device list --context work
# Check status (is the token still valid?)
tailscale-cli auth status
Renewing an expired token
Tailscale tokens expire after 1 to 90 days. When a token expires:
tailscale-cli auth status
# Token: ****abcd1234 (source: system credential store)
# Status: invalid or expired
# Create a new token at https://login.tailscale.com/admin/settings/keys
# Then re-run auth login (the old token is automatically replaced):
tailscale-cli auth login
Usage
Devices
tailscale-cli device list # List all devices
tailscale-cli device list --json # JSON output
tailscale-cli device list --filter isEphemeral=true # Filter
tailscale-cli device get <nodeId> # Device details
tailscale-cli device get <nodeId> --fields all # All fields
tailscale-cli device authorize <nodeId> # Authorize a device
tailscale-cli device deauthorize <nodeId> # Deauthorize
tailscale-cli device expire <nodeId> # Expire the key
tailscale-cli device set-name <nodeId> my-server # Rename
tailscale-cli device set-tags <nodeId> --tags tag:prod # Set tags
tailscale-cli device set-ip <nodeId> 100.80.0.1 # Change IP
tailscale-cli device delete <nodeId> --confirm # Delete
Routes
tailscale-cli device routes list <nodeId>
tailscale-cli device routes set <nodeId> --routes 10.0.0.0/16,192.168.1.0/24
ACL / Policy File
tailscale-cli acl get # Get the ACL
tailscale-cli acl get --format json --details # With details
tailscale-cli acl set --file policy.hujson # Apply an ACL
tailscale-cli acl validate --file policy.hujson # Validate without applying
tailscale-cli acl preview --type user --preview-for admin@company.com --file policy.hujson
DNS
tailscale-cli dns config get # Full DNS config
tailscale-cli dns preferences set --magic-dns true # Enable MagicDNS
tailscale-cli dns nameservers list # List nameservers
tailscale-cli dns nameservers set --nameservers 8.8.8.8,1.1.1.1
tailscale-cli dns searchpaths set --search-paths corp.internal
tailscale-cli dns split update --domain corp.internal --servers 10.0.0.53
Keys (auth keys, API tokens, OAuth)
tailscale-cli key list --all # List all keys
tailscale-cli key create --type auth --reusable --preauthorized --tags tag:ci --expiry 86400
tailscale-cli key get <keyId> # Key details
tailscale-cli key delete <keyId> --confirm # Delete
Users
tailscale-cli user list # List users
tailscale-cli user list --type all --role admin # Filter
tailscale-cli user get <userId> # Details
tailscale-cli user set-role <userId> admin # Change role
tailscale-cli user approve <userId> # Approve
tailscale-cli user suspend <userId> # Suspend
tailscale-cli user restore <userId> # Restore
Webhooks
tailscale-cli webhook list
tailscale-cli webhook create --url https://hooks.slack.com/xxx --provider slack --events nodeCreated,nodeDeleted
tailscale-cli webhook test <id>
tailscale-cli webhook rotate-secret <id>
tailscale-cli webhook delete <id> --confirm
Tailnet Settings
tailscale-cli settings get
tailscale-cli settings update --devices-approval true
tailscale-cli settings update --devices-key-duration 90
tailscale-cli settings update --https true
Services (VIP)
tailscale-cli service list
tailscale-cli service create svc:web --ports tcp:80,tcp:443 --tags tag:prod
tailscale-cli service hosts svc:web
tailscale-cli service approve svc:web <nodeId> --approved true
tailscale-cli service delete svc:web --confirm
Invites
tailscale-cli invite user list
tailscale-cli invite user create --email dev@company.com --role member
tailscale-cli invite device list <nodeId>
tailscale-cli invite device create <nodeId> --email partner@ext.com
Logs
tailscale-cli log audit list --start 2026-04-29T00:00:00Z --end 2026-04-30T00:00:00Z
tailscale-cli log audit list --start ... --end ... --event NODE.CREATE,USER.CREATE
tailscale-cli log network list --start ... --end ...
tailscale-cli log stream status configuration
Environment Variables
| Variable | Description | Default |
|---|---|---|
TSCLI_API_TOKEN | Tailscale API token | β |
TSCLI_TAILNET | Target tailnet | - (token default) |
TSCLI_OUTPUT | Output format: table, json, yaml | table |
TSCLI_DEBUG | Debug mode (true/false) | false |
TSCLI_CONFIG | Config file path | ~/.tailscale-cli/config.json |
TSCLI_CONTEXT | Active context | default |
NO_COLOR | Disable colors | β |
Shell Completion
# Bash
tailscale-cli completion bash > /etc/bash_completion.d/tailscale-cli
# Zsh (add to your .zshrc)
tailscale-cli completion zsh > "${fpath[1]}/_tailscale-cli"
# Fish
tailscale-cli completion fish > ~/.config/fish/completions/tailscale-cli.fish
# PowerShell
tailscale-cli completion powershell > tailscale-cli.ps1
MCP Integration (Claude Code, VS Code, JetBrains)
The CLI includes a built-in MCP (Model Context Protocol) server exposing 39 tools for AI assistants.
Setup
Add to your Claude Code settings (or VS Code / JetBrains with the Claude extension):
{
"mcpServers": {
"tailscale": {
"command": "tailscale-cli",
"args": ["mcp-serve"],
"env": {
"TSCLI_API_TOKEN": "tskey-api-xxxxx"
}
}
}
}
If you already configured the token via
tailscale-cli auth login, the MCP server will automatically use your system credential store β no need for theTSCLI_API_TOKENenv var.
Available MCP Tools
| Tool | Description |
|---|---|
device-list | List all tailnet devices |
device-get | Get device details |
device-authorize | Authorize/deauthorize a device |
device-set-tags | Set device tags |
device-set-name | Rename a device |
device-expire | Expire a device key |
device-delete | Delete a device |
device-routes-list | List device routes |
device-routes-set | Set device routes |
acl-get | Get the policy file (ACL) |
acl-set | Set the policy file |
acl-validate | Validate a policy file |
dns-config-get | Full DNS configuration |
dns-nameservers-list/set | Manage nameservers |
dns-preferences-get/set | MagicDNS on/off |
dns-split-get | Split DNS configuration |
key-list | List keys |
key-create | Create an auth key |
key-get / key-delete | Get / delete a key |
user-list | List users |
user-get / user-set-role | Get details / change role |
user-approve/suspend/restore | Manage user status |
settings-get / settings-update | Tailnet settings |
webhook-list/create/test/delete | Manage webhooks |
service-list/get/hosts | Manage Services |
contact-get | Tailnet contacts |
log-audit-list | Audit logs |
Usage in Claude Code
Once configured, you can simply say:
- "List my Tailscale devices"
- "What tags are defined in my ACLs?"
- "Create a reusable auth key with the tag tag:ci"
- "Enable MagicDNS on my tailnet"
Claude will automatically call the right MCP tools.
Development
# Clone
git clone https://github.com/dimer47/tailscale-cli.git
cd tailscale-cli
# Build
go build -o tailscale-cli .
# Run tests
go test ./...
# Lint
go vet ./...
Creating a new release
git tag v0.3.0
git push origin v0.3.0
# GitHub Actions builds and publishes automatically
License
MIT
