Claude Skill

tailscale-cli

Use when running `tailscale` commands to debug connectivity, inspect status, or manage `tailscale serve`/`funnel`/Services — especially when `tailscale serve status` looks wrong, `tailscale` isn't found in a shell, `tailscale ping` fails against a host that's clearly up, you're w

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download technicalpickles-pickled-claude-plugins-plugins_tailscale_skills_tailscale-cli-85f769c.zip · 13 KB

Install

skills CLI npx skills add https://github.com/technicalpickles/pickled-claude-plugins/tree/main/plugins/tailscale/skills/tailscale-cli
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install technicalpickles-pickled-claude-plugins@llmmart
Git git clone https://github.com/technicalpickles/pickled-claude-plugins.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole technicalpickles/pickled-claude-plugins collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Tailscale CLI

Overview

The tailscale CLI behaves differently depending on install shape (macOS GUI app vs. Linux package) and config model (plain node-level serve vs. --service=svc:X Services). Most "tailscale is broken" moments are actually one of these known gotchas, not a real outage.

For binding/exposure architecture (loopback vs. tailnet-interface binding, identity headers, auth implications) rather than CLI mechanics, see the tailscale-serve-patterns skill instead.

Where the binary lives

Environment Binary Notes
macOS, Tailscale.app (GUI) /Applications/Tailscale.app/Contents/MacOS/Tailscale Not on $PATH — the App Store/direct-download GUI app does not symlink a tailscale command by default. which tailscale returning nothing does not mean Tailscale isn't running; check the menu-bar icon or /Applications/Tailscale.app/Contents/MacOS/Tailscale status directly. Alias it if you use it often: alias tailscale=/Applications/Tailscale.app/Contents/MacOS/Tailscale.
macOS, Homebrew (brew install tailscale) tailscale on $PATH Different install path than the GUI app; if both are present they can diverge in version.
Linux (systemd package, VM/container) tailscale on $PATH, daemon is tailscaled Standard install. Talks to tailscaled over a local socket.

Diagnostic tell: if a ... | jq ... pipeline throws jq: parse error: Invalid numeric literal at line 1, column N, don't debug jq — the upstream command almost certainly failed (e.g. command not found: tailscale) and its error text got merged into stdout via 2>&1, and jq is choking on that text, not real JSON. Re-run the upstream command alone first.

Root/sudo: don't reach for it by default

tailscale status and tailscale ping are normally readable by any local user — no sudo needed. Mutating commands (serve, funnel, up/down in some configs) may need root, or may work passwordless if the local user is set as the tailscale operator (tailscale set --operator=<user>) or granted a scoped NOPASSWD sudo rule for tailscale serve *.

Symptom of getting this wrong: sudo tailscale status --json hangs asking for a password ("a terminal is required to read the password") on a host where plain tailscale status works fine and sudo tailscale serve status also works fine (because sudo is scoped to serve *, not status). Fix: drop the unneeded sudo, or check what the sudoers rule actually covers (sudo -n -l) before assuming Tailscale itself is broken.

Services vs. node-level serve

Two different features that look similar but have separate config and status output — a Service's config is invisible to bare tailscale serve status (it prints No serve config even when fully configured), and a serve command against an undefined Service reports success but does nothing. Full explanation and the fix (serve status --json, .Services): references/services.md.

serve ... off removes the whole port's config, not just your mapping

tailscale serve --https=443 off (or the bare-port form) tears down every path mapping on that port, not just the one you added. Confirmed by running it on a node with two node-level mappings (/ and /readme-preview) to remove only /: serve status --json came back completely empty afterward, both mappings gone. There's no scoped "remove just this path" for node-level serve — tailscale serve --set-path=/some/path off fails outright if that exact path isn't the one currently mapped, and even a successful narrower-looking command can still wipe the shared :443 config underneath it.

If a node has more than one node-level mapping, or you're not sure whether it does: tailscale serve status --json before you touch anything, and after, so you know exactly what existed and can rebuild it (tailscale serve --bg --set-path=<path> <target> per mapping) rather than assuming your teardown was scoped to what you added. This matters most on a shared host, or anywhere state might have been added since you last checked — never assume you're the only thing that's touched serve on that node.

ACLs: tagOwners, grants, and the silent-drop pattern

There's no local tailscale acl command — the policy file only lives in the admin console or the API. A node can join the tailnet fine while silently losing a requested tag it wasn't authorized for (tagOwners), which then breaks something downstream (a grant, an app-level check) without any Tailscale-level error. Recognizing this pattern, tagOwners vs. grants, legacy acls vs. current grants, and reading the live policy via the API: references/acls.md.

Reviewing or validating a policy

Checking a candidate policy with the validate endpoint (it returns 200 on failure), measuring exposure before changing anything, Services as separate grant targets, containers borrowing the host's identity, the Tailscale SSH lockout, auto-approver semantics, and a repeatable audit checklist: references/policy-review.md.

Node key expiry

A peer that used to work and now looks unreachable may just have an expired node key. The symptom is generic (Network unreachable from ssh or ncat, nothing useful from ssh -G or a proxy config), so check before blaming the network, a firewall, or a sandbox:

tailscale status --json | jq '.Peer[] | {HostName, Expired, KeyExpiry}'

Expired: true means the key is dead; re-auth the node. To stop it recurring, use Disable key expiry on the machine in the admin console. Tagging does not clear expiry: a node that joined with a bare tailscale up and was tagged afterwards in the console keeps its key expiry until you disable it separately. When bringing up a long-lived node, pass --advertise-tags on the first up and then disable key expiry.

Setting up a brand-new Service

Has a specific required order (define in admin console → serve --service= → restart tailscaled → approve → validate from a different node) that's easy to get wrong on a first deploy: references/new-service-setup.md.

ping and self-curl gotchas

tailscale ping doesn't work against Service virtual IPs (no matching peer is expected, not a failure), and curling a Service's own hostname from the host that's proxying it can hang even when the Service is healthy for everyone else: references/ping-and-curl-gotchas.md.

Quick troubleshooting checklist: "serve status looks wrong"

  1. Are you checking serve status bare, or --json? Bare misses Services — always add --json for Services.
  2. Did you sudo a command that doesn't need it (or that isn't covered by a scoped sudoers rule)? Try without sudo first.
  3. Is the target a Service (svc:) and does it actually exist in the admin console yet? A serve command against an undefined Service "succeeds" but does nothing.
  4. Are you testing with ping against a Service VIP? Use curl against the hostname instead.
  5. Are you testing from the same host that's serving the proxy? Test from a different node.
  6. Is a Service that was previously working now timing out for everyone, while SSH/ping/tailscale status/container health on the host all look fine? Check whether the host node itself still has its ACL tag (tailscale status --self --json | jq '.Self.Tags', or the Machine detail page in the admin console) before going further — a tag can silently drop from an already-tagged node (e.g. during recovery from an unrelated key-expiry incident), and serve --service= on an untagged host fails with service hosts must be tagged nodes. See references/acls.md and references/services.md.
  7. Is a peer that used to work suddenly unreachable with only a generic Network unreachable? Check tailscale status --json for Expired / KeyExpiry on that peer (see Node key expiry above).
  8. Only after 1-7 are ruled out: check tailscaled itself (systemctl status tailscaled, tailscale status, node's BackendState).

Restarting tailscaled on a shared host is a real action, not a diagnostic one — it affects connectivity for every service that host proxies. Don't do it reflexively while chasing a status-display confusion on an already-working Service; confirm with whoever owns the host first, and reach for it only after ruling out the gotchas above. (Standing up a new Service is different — there the restart is an expected, required step: references/new-service-setup.md.)

Useful commands

Command Purpose
tailscale status Peer list + this node's connection state (no sudo needed normally)
tailscale status --json Same, machine-readable — .Self, .Peer[], .CurrentTailnet, .Health
tailscale serve status --json Real Services + node-serve config — see references/services.md
tailscale ping <peer> WireGuard-level reachability to a real node (not Services)
tailscale version Compare versions across nodes when behavior differs between hosts
tailscale serve --service=svc:X ... off Disable a Service's proxy config (keeps the Service definition)
tailscale serve clear svc:X Remove all serve config for a Service
Files (pickled-claude-plugins)
  • references
    • acls.md 8.2 KB
      Loading…
    • new-service-setup.md 2.1 KB
      Loading…
    • ping-and-curl-gotchas.md 896 B
      Loading…
    • policy-review.md 4.4 KB
      Loading…
    • services.md 2.6 KB
      Loading…
  • SKILL.md 9.9 KB
    ---
    name: tailscale-cli
    description: Use when running `tailscale` commands to debug connectivity, inspect status, or manage `tailscale serve`/`funnel`/Services — especially when `tailscale serve status` looks wrong, `tailscale` isn't found in a shell, `tailscale ping` fails against a host that's clearly up, you're working across a mix of macOS (GUI app) and Linux (VM/container) nodes in the same tailnet, or a node/sidecar joins fine but something downstream (a grant, an app-level check) crash-loops or silently fails — that's often an ACL/tagOwners issue, not a code bug. Also use for authoring or reading tailnet ACLs (tagOwners, grants, the legacy `acls` array) or querying the live policy via the Tailscale API.
    ---
    
    # Tailscale CLI
    
    ## Overview
    
    The `tailscale` CLI behaves differently depending on install shape (macOS GUI app vs. Linux package) and config model (plain node-level `serve` vs. `--service=svc:X` Services). Most "tailscale is broken" moments are actually one of these known gotchas, not a real outage.
    
    For binding/exposure architecture (loopback vs. tailnet-interface binding, identity headers, auth implications) rather than CLI mechanics, see the `tailscale-serve-patterns` skill instead.
    
    ## Where the binary lives
    
    | Environment | Binary | Notes |
    |---|---|---|
    | macOS, Tailscale.app (GUI) | `/Applications/Tailscale.app/Contents/MacOS/Tailscale` | **Not on `$PATH`** — the App Store/direct-download GUI app does not symlink a `tailscale` command by default. `which tailscale` returning nothing does not mean Tailscale isn't running; check the menu-bar icon or `/Applications/Tailscale.app/Contents/MacOS/Tailscale status` directly. Alias it if you use it often: `alias tailscale=/Applications/Tailscale.app/Contents/MacOS/Tailscale`. |
    | macOS, Homebrew (`brew install tailscale`) | `tailscale` on `$PATH` | Different install path than the GUI app; if both are present they can diverge in version. |
    | Linux (systemd package, VM/container) | `tailscale` on `$PATH`, daemon is `tailscaled` | Standard install. Talks to `tailscaled` over a local socket. |
    
    **Diagnostic tell:** if a `... | jq ...` pipeline throws `jq: parse error: Invalid numeric literal at line 1, column N`, don't debug jq — the upstream command almost certainly failed (e.g. `command not found: tailscale`) and its error text got merged into stdout via `2>&1`, and jq is choking on that text, not real JSON. Re-run the upstream command alone first.
    
    ## Root/sudo: don't reach for it by default
    
    `tailscale status` and `tailscale ping` are normally readable by any local user — no `sudo` needed. Mutating commands (`serve`, `funnel`, `up`/`down` in some configs) may need root, *or* may work passwordless if the local user is set as the tailscale operator (`tailscale set --operator=<user>`) or granted a scoped `NOPASSWD` sudo rule for `tailscale serve *`.
    
    Symptom of getting this wrong: `sudo tailscale status --json` hangs asking for a password ("a terminal is required to read the password") on a host where plain `tailscale status` works fine and `sudo tailscale serve status` also works fine (because sudo is scoped to `serve *`, not `status`). Fix: drop the unneeded `sudo`, or check what the sudoers rule actually covers (`sudo -n -l`) before assuming Tailscale itself is broken.
    
    ## Services vs. node-level serve
    
    Two different features that look similar but have separate config and status output — a Service's config is invisible to bare `tailscale serve status` (it prints `No serve config` even when fully configured), and a serve command against an undefined Service reports success but does nothing. Full explanation and the fix (`serve status --json`, `.Services`): [references/services.md](references/services.md).
    
    ## `serve ... off` removes the whole port's config, not just your mapping
    
    `tailscale serve --https=443 off` (or the bare-port form) tears down **every** path mapping on that port, not just the one you added. Confirmed by running it on a node with two node-level mappings (`/` and `/readme-preview`) to remove only `/`: `serve status --json` came back completely empty afterward, both mappings gone. There's no scoped "remove just this path" for node-level serve — `tailscale serve --set-path=/some/path off` fails outright if that exact path isn't the one currently mapped, and even a successful narrower-looking command can still wipe the shared `:443` config underneath it.
    
    If a node has more than one node-level mapping, or you're not sure whether it does: `tailscale serve status --json` before you touch anything, and after, so you know exactly what existed and can rebuild it (`tailscale serve --bg --set-path=<path> <target>` per mapping) rather than assuming your teardown was scoped to what you added. This matters most on a shared host, or anywhere state might have been added since you last checked — never assume you're the only thing that's touched `serve` on that node.
    
    ## ACLs: tagOwners, grants, and the silent-drop pattern
    
    There's no local `tailscale acl` command — the policy file only lives in the admin console or the API. A node can join the tailnet fine while silently losing a requested tag it wasn't authorized for (`tagOwners`), which then breaks something downstream (a grant, an app-level check) without any Tailscale-level error. Recognizing this pattern, tagOwners vs. grants, legacy `acls` vs. current `grants`, and reading the live policy via the API: [references/acls.md](references/acls.md).
    
    ## Reviewing or validating a policy
    
    Checking a candidate policy with the validate endpoint (it returns 200 on failure), measuring exposure before changing anything, Services as separate grant targets, containers borrowing the host's identity, the Tailscale SSH lockout, auto-approver semantics, and a repeatable audit checklist: [references/policy-review.md](references/policy-review.md).
    
    ## Node key expiry
    
    A peer that used to work and now looks unreachable may just have an expired node key. The symptom is generic (`Network unreachable` from `ssh` or `ncat`, nothing useful from `ssh -G` or a proxy config), so check before blaming the network, a firewall, or a sandbox:
    
    ```bash
    tailscale status --json | jq '.Peer[] | {HostName, Expired, KeyExpiry}'
    ```
    
    `Expired: true` means the key is dead; re-auth the node. To stop it recurring, use **Disable key expiry** on the machine in the admin console. Tagging does not clear expiry: a node that joined with a bare `tailscale up` and was tagged afterwards in the console keeps its key expiry until you disable it separately. When bringing up a long-lived node, pass `--advertise-tags` on the first `up` and then disable key expiry.
    
    ## Setting up a brand-new Service
    
    Has a specific required order (define in admin console → `serve --service=` → restart `tailscaled` → approve → validate from a different node) that's easy to get wrong on a first deploy: [references/new-service-setup.md](references/new-service-setup.md).
    
    ## `ping` and self-curl gotchas
    
    `tailscale ping` doesn't work against Service virtual IPs (`no matching peer` is expected, not a failure), and curling a Service's own hostname from the host that's proxying it can hang even when the Service is healthy for everyone else: [references/ping-and-curl-gotchas.md](references/ping-and-curl-gotchas.md).
    
    ## Quick troubleshooting checklist: "serve status looks wrong"
    
    1. Are you checking `serve status` bare, or `--json`? Bare misses Services — always add `--json` for Services.
    2. Did you `sudo` a command that doesn't need it (or that isn't covered by a scoped sudoers rule)? Try without `sudo` first.
    3. Is the target a Service (`svc:`) and does it actually exist in the admin console yet? A serve command against an undefined Service "succeeds" but does nothing.
    4. Are you testing with `ping` against a Service VIP? Use `curl` against the hostname instead.
    5. Are you testing from the same host that's serving the proxy? Test from a different node.
    6. **Is a Service that was previously working now timing out for everyone, while SSH/ping/`tailscale status`/container health on the host all look fine?** Check whether the host node itself still has its ACL tag (`tailscale status --self --json | jq '.Self.Tags'`, or the Machine detail page in the admin console) before going further — a tag can silently drop from an already-tagged node (e.g. during recovery from an unrelated key-expiry incident), and `serve --service=` on an untagged host fails with `service hosts must be tagged nodes`. See `references/acls.md` and `references/services.md`.
    7. Is a peer that used to work suddenly unreachable with only a generic `Network unreachable`? Check `tailscale status --json` for `Expired` / `KeyExpiry` on that peer (see Node key expiry above).
    8. Only after 1-7 are ruled out: check `tailscaled` itself (`systemctl status tailscaled`, `tailscale status`, node's `BackendState`).
    
    **Restarting `tailscaled` on a shared host is a real action, not a diagnostic one** — it affects connectivity for every service that host proxies. Don't do it reflexively while chasing a status-display confusion on an *already-working* Service; confirm with whoever owns the host first, and reach for it only after ruling out the gotchas above. (Standing up a *new* Service is different — there the restart is an expected, required step: [references/new-service-setup.md](references/new-service-setup.md).)
    
    ## Useful commands
    
    | Command | Purpose |
    |---|---|
    | `tailscale status` | Peer list + this node's connection state (no sudo needed normally) |
    | `tailscale status --json` | Same, machine-readable — `.Self`, `.Peer[]`, `.CurrentTailnet`, `.Health` |
    | `tailscale serve status --json` | Real Services + node-serve config — see [references/services.md](references/services.md) |
    | `tailscale ping <peer>` | WireGuard-level reachability to a real node (not Services) |
    | `tailscale version` | Compare versions across nodes when behavior differs between hosts |
    | `tailscale serve --service=svc:X ... off` | Disable a Service's proxy config (keeps the Service definition) |
    | `tailscale serve clear svc:X` | Remove all serve config for a Service |
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.