tscli

tscli is a fast, single-binary CLI for the Tailscale HTTP API. From your terminal you can manage devices, users, auth keys, webhooks, posture integrations, tailnet-wide settings, and even hit raw endpoints when the SDK hasn’t caught up yet.

✨ Highlights

Area	What you can do
Devices	List, get, (de)authorize, rename, force IPv4, enable subnet routes, expire, set / delete posture attributes
Keys	List & get existing keys; create auth-keys or OAuth clients (with full scope/tag validation)
Users	List (filter by type / role), get, suspend / restore / approve, manage invites
Tailnet settings	Get & patch booleans + key-expiry with a single command (tscli set settings …)
Policy file (ACL)	Fetch as raw HUJSON or canonical JSON
Webhooks	List, get, delete, create (generic / Slack) with subscription & provider validation
Posture integrations	List, get, create, patch existing integrations
Invites	List / delete device- or user-invites
Contacts	Get & update contact emails
Debug switch	--debug or TSCLI_DEBUG=1 prints full HTTP requests / responses to stderr
Config precedence	flags → env → ~/.tscli/.tscli.yaml (or local ./.tscli.yaml)

🔧 Install

🔧 Installation

macOS / Linux (Homebrew)

brew tap jaxxstorm/tap
brew install tscli          # upgrades via ‘brew upgrade’

Windows (Scoop)

scoop bucket add jaxxstorm https://github.com/jaxxstorm/scoop-bucket.git
scoop install tscli

Nix

nix shell github:jaxxstorm/tscli

Manual download

Pre-built archives for macOS, Linux, Windows (x86-64 / arm64) are published on every release:

# install the newest tscli (Linux/macOS, amd64/arm64)
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
case $ARCH in
  x86_64) ARCH=amd64 ;;
  aarch64|arm64) ARCH=arm64 ;;
esac

curl -sSL "$(curl -sSL \
  https://api.github.com/repos/jaxxstorm/tscli/releases/latest \
  | grep -oE "https.*tscli_.*_${OS}_${ARCH}\.tar\.gz" \
  | head -n1)" \
| sudo tar -xz -C /usr/local/bin tscli

Go install (always builds from HEAD)

go install github.com/jaxxstorm/tscli@latest

After any method, confirm:

tscli --version

⚙️ Configuration

Option	Flag / Env var	YAML key	Default
Tailscale API key	--api-key, -k / TAILSCALE_API_KEY	api-key	—
Tailnet name	--tailnet, -n / TAILSCALE_TAILNET	tailnet	—

# ~/.tscli/.tscli.yaml
api-key: tskey-abc123…
tailnet: example.com
output: pretty # other options are: human, json or yaml

🚀 Usage

tscli <noun> <verb> [flags]

Global flags

-k, --api-key string   Tailscale API key
-n, --tailnet string   Tailnet (default "-")
-d, --debug            Dump raw HTTP traffic to stderr

📜 Coverage

API Area / Action	Status	tscli Command
Devices
List tailnet devices	✅	tscli list devices
Get a device	✅	tscli get device --device <device>
Delete a device	✅	tscli delete device --device <device>
Expire a device key	✅	tscli set device expiry --device <device>
List device routes	✅	tscli list routes --device <device>
Set device routes	✅	tscli set device routes --device <device> --route <cidr>
Authorize / de-authorize device	✅	tscli set device authorization --device <device> --approve=<bool>
Set device name	✅	tscli set device name --device <device> --name <hostname>
Set device tags	✅	tscli set device tags --device <device> --tag tag:<tag>
Update a device key	✅	tscli set device key --device <device> --disable-expiry|--enable-expiry
Set device IPv4 address	✅	tscli set device ip --device <device> --ip <ip>
Get posture attributes	✅	tscli get device posture --device <device>
Set custom posture attributes	✅	tscli set device posture --device <device> --key custom:x --value <v>
Delete custom posture attributes	✅	tscli delete device posture --device <device> --key custom:x
Policy File
Get policy file	✅	tscli get policy [--json]
Set policy file	✅	tscli set policy --file <acl.hujson>
Preview rule matches	✅	tscli get policy preview --type user|ipport --value … [--current|--file F]
Validate / test policy	✅	tscli get policy validate --file <policy.json>
Keys
List tailnet keys	✅	tscli list keys
Create auth-key / OAuth client	✅	tscli create key --type authkey --oauthclient …
Get key	✅	tscli get key --key <id>
Delete / revoke key	✅	tscli delete key --key <key-id>
Create a token	✅	tscli create token --client-id <oauth-client-id> --client-secret <oauth-client-secret>
DNS
List DNS nameservers	✅	tscli list nameservers
Set DNS nameservers	✅	tscli set nameservers --nameserver <ip> …
Get DNS preferences	✅	tscli get dns preferences
Set DNS preferences	✅	tscli set dns preferences --magicdns=<bool>
List DNS search paths	✅	tscli list dns searchpaths
Set DNS search paths	✅	tscli set dns searchpaths --searchpath <domain> …
Get split-DNS map	✅	tscli get dns split
Update split-DNS	✅	tscli set dns split --domain <d>=<ip,ip> …
Set split-DNS	✅	tscli set dns split --replace --domain <d>=<ip>
Logging
List configuration audit logs	✅	tscli list logs config --start <t> [--end <t>]
List network flow logs	✅	tscli list logs network --start <t> [--end <t>]
Get log-streaming status	✅	`tscli get logs stream --type {configuration
Get log-streaming configuration	✅	`tscli get logs stream --type {configuration
Create or get AWS external id.	✅	tscli get logs aws [--reusable]
Validate external ID integraton with IAM role trust policy	✅	tscli get logs aws validate --external-id <id> --role-arn <arn>
Users
List users	✅	tscli list users [--type …] [--role …]
Get a user	✅	tscli get user --user <id>
Update user role	✅	tscli set user-role --user <id> --role <role>
Approve / suspend / restore user	✅	tscli set user-access --user <id> --approve|--suspend|--restore
Delete a user	✅	tscli delete user --user <id>
User Invites
List user invites	✅	tscli list invites user [--state …]
Create user invite	✅	tscli create invite user --email <email> [--role <role>]
Get a user invite	✅	tscli get user invite --id <invite-id>
Delete a user invite	✅	tscli delete user invite --id <invite-id>
Resend user invite	✅	tscli set user invite --id <invite-id> --resend
Device Invites
List device invites	✅	tscli list invites device --device <device>
Create device invite	✅	tscli create invite device --device <device> --email <email>
Get a device invite	✅	tscli get device invite --id <invite-id>
Delete a device invite	✅	tscli delete device invite --id <invite-id>
Resend / accept device invite	✅	tscli set device invite --id <invite-id> --status <resend|accept>
Posture Integrations
List integrations	✅	tscli list posture-integrations
Create integration	✅	tscli create posture-integration --provider <p> …
Get integration	✅	tscli get posture-integration --id <id>
Update integration	✅	tscli set posture-integration --id <id> …
Delete integration	✅	tscli delete posture-integration --id <id>
Contacts
Get contacts	✅	tscli get contacts
Update contact	✅	tscli set contacts --contact <id> --email <e@x>
Resend verification	✅	tscli set contact --type <type> --resend
Webhooks
List webhooks	✅	tscli list webhooks
Create webhook	✅	tscli create webhook --url <endpoint> …
Get webhook	✅	tscli get webhook --webhook <id>
Update webhook	✅	tscli set webhook --webhook <id> …
Delete webhook	✅	tscli delete webhook --webhook <id>
Test webhook	✅	tscli get webhook test
Rotate webhook secret	✅	tscli rotate webhook --webhook <id>
Tailnet Settings
Get tailnet settings	✅	tscli get settings
Update tailnet settings	✅	tscli set settings --devices-approval …

Quick examples

# Approve a waiting device
tscli device authorize --device node-abc123 --approve

# Rotate an auth-key that expires in 30 days
tscli create key --description "CI" --expiry 720h | jq .key

# Create Slack webhook for device deletions
tscli create webhook \
  --url https://hooks.slack.com/services/T000/B000/XXXXX \
  --provider slack \
  --subscription nodeDeleted

🛠 Development

git clone https://github.com/jaxxstorm/tscli
cd tscli
TAILSCALE_API_KEY=tskey-… TAILSCALE_TAILNET=example.com go run ./cmd/tscli list devices

Tests & lint:

go test ./...

📄 License

MIT — see LICENSE.