query-ts

A command-line tool for querying the Tailscale API. List and filter devices, users, groups, services, and ACLs using a small, glob-friendly query language, and render the results as a table, JSON, YAML, or plain text.

Features

• Query devices (default), users, groups, services, and ACLs.
• A simple filter DSL with glob matching, tag matching, AND/OR, parentheses, and negation.
• Human-friendly coloured tables by default, plus --json, --yaml, and --plain output for scripting.
• Authenticates with either a Tailscale API key or OAuth2 client credentials (tokens fetched and cached automatically).

Installation

Install with Homebrew:

brew install 1stvamp/tap/query-ts

Or with snap:

sudo snap install query-ts

Or from PyPI with your tool of choice:

pip install query-ts
# or, to install as an isolated tool:
uv tool install query-ts
# or:
pipx install query-ts

This installs a query-ts command and requires Python 3.11+.

To run from a checkout instead (the project is managed with uv):

uv run query-ts --help

Authentication

Provide either an API key or OAuth2 client credentials, not both. One of the two is required; the CLI exits with an error if no credentials are given.

API key

export TAILSCALE_API_KEY="tskey-api-..."
# or pass it inline with -k/--api-key

OAuth2 client credentials

Both the ID and secret are required together:

export TAILSCALE_OAUTH_CLIENT_ID="..."
export TAILSCALE_OAUTH_CLIENT_SECRET="..."
# or pass --oauth-client-id and --oauth-client-secret

An access token is obtained via the client_credentials grant and cached for its lifetime, refreshing automatically before it expires.

Tailnet

By default the authenticated user's own tailnet (-) is used. Override it with -n/--tailnet or the TAILSCALE_TAILNET environment variable.

Usage

query-ts [QUERY] [OPTIONS]

QUERY is an optional filter expression. Without it, all resources of the selected type are listed.

# All devices, as a table
query-ts

# Devices whose name starts with "web-"
query-ts 'web-*'

# Production-tagged devices that aren't deprecated
query-ts 'env:production -tag:deprecated'

# Users matching a pattern
query-ts --users 'admin*'

# JSON output for two name patterns
query-ts --json 'web-* OR api-*'

# Comma-separated device names (implies plain output)
query-ts --comma 'env:prod'

# List ACL groups
query-ts --type=groups

Query language

Patterns are glob-style (fnmatch) and matched case-insensitively against resource names.

Name patterns

Tag patterns

A word containing a colon is treated as a tag filter. The prefix:suffix form expands to the tag prefix-suffix:

Logical operators

AND and OR are case-insensitive.

Negation

A leading - negates a term:

query-ts '-web-*'            # exclude names matching web-*
query-ts '-tag:env-prod'     # exclude tagged resources

A query that begins with - (such as a negation) would otherwise be mistaken for a command-line option. Use -- to stop option parsing and pass it as the query:

query-ts -- -web-*          # exclude names matching web-*

Options

Resource type

Output format

The default format is a coloured table.

Plain-text output

These options only affect plain output. When --field is omitted, a default is chosen per resource type (hostname for devices, login for users).

Connection & authentication

Display

Responsive tables

The default table output adapts to your terminal width. When space is tight it degrades gracefully: list columns (IP addresses, tags, members) wrap onto multiple lines first, then the lowest-priority columns are dropped, then long values are shortened (emails lose their domain, timestamps drop the time). Hostname and Tags are never dropped.

For devices, Last Seen is hidden by default and the online state is shown as a coloured dot in the Online column. Use --show last-seen to add the timestamp column, or name any columns you always want kept in full, e.g. --show ip,tags,last-seen. Columns passed to --show are exempt from the automatic dropping and shortening.

A device counts as online if it holds a live connection to the Tailscale control server, or if it was last seen within the --online-window (default 5 minutes). The Tailscale API has no plain online flag, and idle-but-reachable devices (phones in particular) drop the control connection, so widen the window if such devices read as offline, e.g. --online-window 15.

Development

# Install dependencies (including dev tools)
uv sync

# Run the test suite
uv run pytest tests/ -v

Tests use respx to mock the Tailscale HTTP API, so no real credentials or network access are required.

License

Apache-2.0