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

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 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

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github/workflows		.github/workflows
cmd		cmd
docs		docs
internal		internal
testdata/fixtures		testdata/fixtures
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
README.fr.md		README.fr.md
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation

tailscale-cli

Features

Prerequisites

Installation

Method 1: Download the binary (recommended)

Method 2: From source (requires Go 1.21+)

Method 3: Build locally

Verify installation

Updating

Quick Start

1. Get a Tailscale API token

2. Configure the CLI

3. Test it

Configuration

Token resolution priority

Multi-context (multiple Tailscale accounts)

Renewing an expired token

Usage

Devices

Routes

ACL / Policy File

DNS

Keys (auth keys, API tokens, OAuth)

Users

Webhooks

Tailnet Settings

Services (VIP)

Invites

Logs

Environment Variables

Shell Completion

MCP Integration (Claude Code, VS Code, JetBrains)

Setup

Available MCP Tools

Usage in Claude Code

Development

Creating a new release

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages