---
name: tailscale
description: 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

```bash
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.