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:

# example for Linux amd64
curl -sSfL \
  https://github.com/jaxxstorm/tscli/releases/latest/download/tscli_$(uname -s)_$(uname -m).tar.gz \
  | 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
format: 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 devices	✅	device list
get device	✅	device get --device <id>
authorize / de-authorize device	✅	device authorize --device <id> [--approve=<bool>]
expire device key	✅	device expire --device <id>
set device name	✅	set name --device <id> --name <host>
set device tags	✅	set tags --device <id> --tag <tag>
set device IPv4	✅	set ip --device <id> --ip <addr>
list subnet routes	✅	list routes --device <id>
set subnet routes	✅	set routes --device <id> --route <cidr> …
delete device	✅	delete device --device <id>
Device-posture attributes
get attributes	✅	get posture --device <id>
set attribute	✅	set attribute --device <id> --key custom:x --value 42
delete attribute	✅	delete attribute --device <id> --key custom:x
Posture integrations
list integrations	✅	list posture-integrations
get integration	✅	get posture-integration --id <id>
create integration	✅	create posture-integration --provider …
update integration	✅	set posture-integration --id <id> …
delete integration	❌	—
Auth / OAuth keys
list keys	✅	list keys
get key	✅	get key --key <id>
create auth-key	✅	create key --type authkey …
create OAuth client	✅	create key --type oauthclient …
delete / revoke key	❌	—
Users
list users	✅	list users [--type …] [--role …]
get user	✅	get user --user <id>
approve / suspend / restore user	✅	set user-access --user <id> --approve/--suspend/--restore
delete user	✅	delete user --user <id>
Invites
list user invites	✅	list invites user [--state …]
list device invites	✅	list invites device --device <id>
delete invite	❌	—
get invite	❌	—
Contacts
update contact	✅	set contacts --contact <id> --email <e@x>
list / create / delete contacts	❌	—
DNS
list nameservers	✅	list nameservers
set nameservers	✅	set nameservers --nameserver <ip> …
advanced DNS settings	❌	—
Policy file (ACL)
get policy file	✅	get policy [--json]
set policy file	✅	set policy --file <acl.hujson>
preview rule matches	✅	get policy-preview --type … --value … [--file]
policy history / tests	❌	—
Tailnet settings
get settings	✅	get settings
update settings	✅	set settings --devices-approval …
Webhooks
list webhooks	✅	list webhooks
get webhook	✅	get webhook --webhook <id>
create webhook	✅	create webhook --url <endpoint> --subscription …
update webhook	✅	set webhook --webhook <id> …
delete webhook	✅	delete webhook --webhook <id>
rotate webhook secret	❌	—

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.