claudetools/.claude/commands/tailscale.md

name, description

name	description
tailscale	Manage an ACG-administered Tailscale tailnet via the REST API v2 - list/inspect devices, delete a node, authorize a device, create/list/revoke tagged pre-auth keys. Reads free; writes gated --confirm.

/tailscale — Tailscale tailnet management (REST API v2)

Thin entry point to the tailscale skill. Engine: .claude/skills/tailscale/scripts/tailscale-api.sh. Full reference: .claude/skills/tailscale/SKILL.md. Doctrine (per-client tailnets, tagged pre-auth keys, offboarding): wiki/patterns/tailscale-client-management.md.

Read-only by default; every device delete/authorize and auth-key create/delete is gated behind --confirm and previews first. ADMIN rights: add + delete.

Usage

TS="bash .claude/skills/tailscale/scripts/tailscale-api.sh"

# Reads (no confirm)
$TS status                                   # auth check + tailnet + device count
$TS devices [--json]                         # list devices
$TS device <name|id|100.x> [--json]          # device detail
$TS keys [--json]                            # list auth keys

# Writes (GATED — preview without --confirm, act with it)
$TS create-key --tag tag:<client> --reusable --preauth [--ephemeral] \
   [--expiry-days N] [--desc "..."] --confirm
$TS delete-key <keyId> --confirm             # revoke an auth key
$TS authorize <name|id|100.x> --confirm      # approve a device
$TS delete-device <name|id|100.x> --confirm  # remove a node

# Point at a specific per-client tailnet's vault entry
$TS devices --vault tailscale/roberts.sops.yaml

Rules

1. Vault-first auth. Credentials come from tailscale/api-access.sops.yaml (OAuth client preferred, credentials.api_key token fallback); tailnet defaults to -. Never hardcode a token. Provisioning commands are in the skill doc.
2. Read before write. Device ops resolve a name/100.x to the stable id first; an ambiguous match STOPS (lists candidates, does nothing) — pass a specific id.
3. Gated writes. No --confirm = preview + exit, no change. Deleting a node drops it off the tailnet; revoking a key blocks future enrollments with it.
4. Per-client isolation. One tailnet per client, one vault entry per tailnet. Confirm the --vault/tailnet before any write.
5. Key secrets → vault, never chat/commit. create-key prints the secret once; store it via /vault immediately.
6. Bot alert after every write. Successful writes auto-post a [TAILSCALE] ... line to Discord (soft-fail); reads do not.

Use this to drive the tailnet; use /rmm to push the tagged pre-auth key onto client machines (tailscale-client-enroll.ps1) once a key is minted.