tailscale-cli

CLI for the Tailscale API v2 — manage your tailnet from the terminal.

Documentation en francais

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

1. Log in to the Tailscale admin console
2. Go to Settings > Keys
3. Click Generate API access token
4. Choose the expiration duration (1 to 90 days)
5. 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 the TSCLI_API_TOKEN env 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