The command-line tool to wrangle your Tailscale tailnet cluster whether large or small.

What is tips?

Any Tailscale user whether a hobbyist with a 3 node cluster or a seasoned cloud professional managing thousands of production nodes can benefit from this tool. tips is the go-to tool to quickly and effectively manage an ever growing tailnet cluster. It allows you to confidently slice | dice | filter nodes, remotely execute commands, and manage your nodes collectively using an effective pattern modeled after cloud automation software.

Features

• 😎 - A richer experience when ran on a node within the tailnet network
• 📝 - Nearly zero-config managed via Viper and Cobra, with sane defaults
• ⚡️ - Caching and indexed via BBolt key-value store for fast queries
• 🔎 - Powerful complex filtering expression, sorting, slicing and dicing built-in
• 👩‍💻‍ - Developer focused tooling
• ✅ - Remote command execution and ssh tooling built-in
• 🫦 - Beautifully rendered terminal output thanks to Charmbracelet's lipgloss
• 👍🏼 - No deployable dependencies, single binary thanks to the Go programming language

---

Table of Contents

• Installation
• Definitions
• Why the name?
• How to Guide
• Built with ❤️
• F.A.Q.
• Alpha Status
• Disclaimer

---

Installation

First, grab the tips binary by doing a typical install from source:

$ go install github.com/deckarep/tips@latest

Next, log into your Tailscale account and create an API Access token.

1. Link to create API Access token
2. Under API Access Tokens click: Generate access token...
3. Provide a Description like tips-cli and choose an expiry time or keep the 90 days default.
4. After clicking the Generate button copy the key that looks like: tskey-api-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx and save it in the tips config file.
5. Follow security best-practices by not sharing this key or copying it into a public repo!
6. tips uses this key to remotely access the Tailscale Web API.

At an absolute minimum tips requires the tips_api_key and a tailnet to be specified in order to use this app. Here is how you can set this up.

As an environment variable:

export TIPS_API_KEY=tskey-api-xxxxxxxxxxxx-xxx...
export TAILNET=user@domain.com

Or, in the ~/.tips.cfg JSON file placed in your homedir:

{
    "tips_api_key": "tskey-api-xxxxxxxxxxxx-xxx...",
    "tailnet": "user@domain.com"
}

Lastly, on-demand by using the relevant flags:

# This will get tedious and not recommended long term
$ ./tips --tailnet user@domain.com --tips_api_key tskey-api-xxxxxxxxxxxx-xxx...

Definitions

• Tailscale: makes creating software-defined networks easy: securely connecting users, services, and devices
• tailnet: a single private network built from one or more nodes using Tailscale
• tips (this tool): a command-line tool to easily manage a tailnet cluster for use on Mac, PC, or Linux

You'll be able to ...

• Easily view your nodes in a beautifully rendered and consistent table view
• View enriched, realtime info such as online status when ran from the context of a node within a tailnet
• Filter nodes based on: tags, OS, hostname and other fields
• Slice or segment nodes to work on a portion of them at a time
• Easily ssh into a node
• Execute single-shot complex commands against all matching nodes in parallel with controllable concurrency
• Tail the logs of long-running sessions from multiple nodes
• Broadcast commands to multiple nodes using the csshx power-tool if installed
• Quickly generate a , or \n delimited list of nodes for reporting or use in other apps/cli tools
• Quickly generate a json list of nodes

...with automatic but configurable file-system caching built-in which means fast, consistent results everytime!

Why the name?

• The name must be short, this tool must not get in the way and will likely be often used to query infrastructure
• Simply put, this tool is about managing a (t)ailnet's distributed (ips) or nodes which shortens to: tips
• Lastly, what better way to show appreciation for software than to leave a tip especially if used in a professional or commercial setting?

How To Guide

Here is a list of common commands from easy to more advanced.

How do I use this command-line tool?

# Here is the general layout, how to use it as everything practically everything is optional by default.
./tips [optional-primary-devices-filter] [optional-remote-command] --flags param0, param1, --moreflags

How do I get a list of all devices or nodes in a tailnet?

./tips
./tips @ # This is equivalent as @ means all/everything.

However, it's better to query by a full name or prefix especially if you have a large infrastructure

# Simply provide a partial or full string name.
./tips [prefix]

./tips blade # Find all nodes with a machine name starting with 'blade'

./tips bla # Find all nodes with a machine name starting with 'bla'

# Multiple are supported too, but must be in quotes.
./tips "[prefix-0] | [prefix-1] ... | [prefix-n]"

# Find all nodes starting with: 'foo' or 'bar' or 'baz'
./tips "foo | bar | baz"

# Lastly, you can also slice the result.
./tips "[prefix-0] | [prefix-1] ... | [prefix-n] [optional-slice]"

# Does a prefix search on foo OR bar and returns the results from 5 to 10.
# NOTE: when more than one prefix is provided, this acts as multiple indexed searches.
./tips "foo | bar [5:10]"

How can I further filter?

# Comma delimited filtering is an AND-type conditional: this returns all devices that match both linux AND user@foo.com 
./tips --filter 'linux, user@foo.com'

# Pipe delimited is an OR-type conditional: this returns all devices that match both linux OR user@foo.com 
./tips --filter 'linux | user@foo.com'

# Complex/nested filtering is supported with parentheses having precedence.
./tips --filter '(linux, (peanuts | walnuts), (user@foo.com | them@website.com))'

# Glob-style filtering as prefix, suffix or a combination of both works too!
./tips --filter '1.54*, *foo.com, *dog*'

How do I get more details?

# Not yet supported, need to think about what this even does.
# ./tips --details

How do I sort the output?

# Partially working (some fields not supported)
# To sort by one column ascending (default)
./tips --sort 'name'

# To sort by multiple columns with varying order, specifically in ascending or descending order
./tips --sort 'name:dsc,email:asc'

How do I slice/partition nodes?

# Shows only the first 5 nodes
./tips --slice '[0:5]'

# Shows the nodes from 5 to 10
./tips --slice '[5:10]'

# Show nodes from 5 on up
./tips --slice '[5:]'

How do I add/remove columns to be returned?

# List one or more columns to additionally include beyond the default
# ./tips --columns 'ipv6, authorized'

# By prefixing with a - (dash) you can exclude one or more columns
# ./tips --columns '-ipv4, -user'

# Or you can do a combination of include and exclude
# ./tips --columns 'ipv6, -user'

How do I generate a JSON-based result

./tips --json

How do I generate a list of ips only

# Provides a \n delimited list of ips
./tips --ips

# Provides a comma delimited list of ips
./tips --ips --delimiter ','

How do run a remote command on all returned nodes?

./tips [prefix-filter] [remote command here]

./tips blade "hostname" # runs the remote command 'hostname' on all nodes that start with prefix:blade

./tips bla "echo 'hello'" -c20 # same as above but does an echo with a concurrency value of 20.

How do I rebuild the index? Running this forces a full rebuild (fetch all remote data) and builds the index for speedy queries. Normally you don't have to do this manually.

# Not yet supported
# ./tips --reindex

Supported/Tested OS's

• MacOS (actively developed, tested)
• Linux (planned soon, untested, may work to some degree)
• PC (future planned, untested, contributions welcome)

Built with ❤️

• by deckarep

F.A.Q.

Q: I'm having trouble executing remote commands on some nodes in my tailnet.

A: This is typically not a problem with this tool, but rather your tailnet configuration with respect to permissions or tagging or ssh auth keys. Please check that your nodes have the appropriate ports open, permissions and/or public keys to match your user logon credentials.

Q: I'm having trouble sshing into a node with this tool.

A: This tool does absolutely nothing special to manage ssh-based logins and simply forwards such requests to either the Tailscale ssh subcommand or the native ssh executable. Please see the previous question as for what could be wrong.

Q: I have a massive infrastructure. Will this tool help me manage a large infrastructure with 10's of thousands of nodes?.

A: Yes, with robust caching and indexing built-in, this tool ensures fast queries amongst even the largest clusters. One of the primary goals of this project is that it can help you manage a tailnet from 5 to 50,000 nodes. It all boils down to the indexing/caching strategies, and it largely depends on query use cases.

Q: How can I execute remote commands with a greater degree of parallelism or concurrency?

A: We have you covered: see the -c or --concurrency flag.

Q: When executing remote commands how can I view stderr as well as stdout?

A: Use the --stderr flag.

A: Use the --nocolor flag.

Q: How can I disable colored output?

A: See the --nocolor flag.

Q: Isn't caching with BBolt overkill?

A: Probably, but integration is easy and some users are expected to be managing thousands of nodes via Tailscale.

Q: But why u no have unit-tests?

A: Because this is a prototype! I am rapidly designing what I think this software should look like and in this phase, unit-tests will slow me down. I've already gone through several major refactors and will likely have more coming up but this will change. Eventually the design will be nailed down and unit-tests will be a must!

Alpha

This code is currently being developed in a rapid prototyping mode. Therefore you will not see much unit-testing as too much code is changing and being actively refactored as the design and approach is tightened up. If you use this at this stage please understand that things are bound to change or be broken until I promote this software to being at the "beta" stage. Currently only MacOS builds are working.

Disclaimer: Independent Project

Please note that this project is a personal and independent initiative. It is not endorsed, sponsored, affiliated with, or otherwise associated with any company or commercial entity. This project is developed and maintained by individual contributors in their personal capacity. The views and opinions expressed here are those of the individual contributors and do not reflect those of any company or professional organization they may be associated with.