tailscale/docs/cli.md

Tailscale CLI evolution guidelines

This document offers guidance for evolving the Tailscale core command-line interface(s), principally tailscale (and, where relevant, tailscaled). It is intentionally lightweight. It describes the spirit we want to preserve as the CLI grows, not a rigid specification. As with all style guides, some of it is subjective and exists mainly to codify existing conventions and promote consistency; other parts have stronger reasoning, such as compatibility, accessibility, or long-term maintenance burden.

When a guideline here conflicts with good judgement in a specific case, prefer good judgement, but raise the conflict so the guidance can be improved. These are defaults and tie-breakers, not laws.

Collaboration and design review

CLI design is a collaborative process, and these guidelines are best applied in conversation rather than in isolation.

Tailscalars should seek collaboration in the #cli channel in Slack for design reviews early, before significant implementation work, while a design is still easy to change.

Open-source contributors should anticipate feedback on CLI changes and expect to be asked to approach design review collaboratively and thoughtfully. CLI surface is long-lived and hard to change once shipped, so a proposed change may go through more discussion than a typical bug fix. This is not a barrier; it is how we keep the CLI coherent. Engaging openly with that review process is the fastest path to getting a change merged.

Influences and non-goals

Some good concepts and vocabulary here are drawn from the Fuchsia CLI guidelines:

• https://fuchsia.dev/fuchsia-src/development/api/cli
• https://fuchsia.dev/fuchsia-src/development/api/cli_help

We borrow ideas, not rules. Those documents are more prescriptive than we want to be, and several of their specifics do not apply to us. In particular:

• We are not adopting their --help output format. Our help output has its own history and conventions, and we will not switch formats arbitrarily.
• We have many pre-existing commands and behaviors that predate any of this guidance. We accept them as-is. This document is about how we grow from here, not a mandate to retrofit existing surfaces.

Guiding principles

The Tailscale CLI is one of the most visible parts of the product. It is used interactively by humans, embedded in scripts and pipelines, read by screen readers, and depended on for automation. Small decisions compound. We would rather do the harder work of getting a surface right than take the easier short-term path of adding one more toggle.

Keep overall configurability low

We aim to keep the overall configurability of the Tailscale client low. It is strongly preferred to identify broadly common solutions to heterogeneous user challenges and apply them holistically, rather than exposing large configuration surfaces.

Wide configuration surfaces are deceptively expensive: they invite users to spend effort tuning them, they increase the support load, they multiply the combinations we must test and reason about, and they tend to ossify into compatibility obligations. Prefer doing the hard work of getting the default right over the easy "now" work of adding another option.

This is a default bias, not an absolute prohibition. When a setting is genuinely necessary, add it deliberately and in the right place (see below).

Command structure

Top-level commands

The top-level command surface (tailscale <command>) is precious. Every addition there is effectively permanent and competes for the user's attention and memory. We want it to grow slowly.

Some commands earn a place at the top level because they are used so frequently that the brevity is worth it:

• tailscale set and tailscale get are fine as independent top-level commands, in large part because their usage is so frequent. The cost of an extra level of nesting would be paid constantly.

Prefer tailscale <noun> <verb> for features

For new "feature"-oriented designs, we will generally prefer a tailscale <noun> <verb> structure (for example tailscale <feature> status, tailscale <feature> enable). This lets a feature's surface grow over time without growing the top-level CLI surface too quickly. New verbs and options live under the noun, where they are discoverable in context and do not crowd the root.

This is a guideline, not a cage. Do not force a design into <noun> <verb> if there is wide consensus that the resulting structure is awkward. Naturalness and usability win over structural purity.

Noun naming

Prefer singular nouns (tailscale cert, tailscale ip) unless a singular form is strongly unnatural for the concept. Consistency in number makes commands easier to predict and remember.

tailscale up is closed for extension

tailscale up is now effectively closed for extension. New configuration features should prefer to go into set rather than up.

The reason is historical and concrete: up has the long-standing problem that its flags describe a desired complete state, so a later invocation must repeat (or carefully manage) all of the earlier flags or risk resetting them. set was introduced precisely to allow incremental, additive configuration changes without that footgun. New knobs belong there.

Extend existing surfaces when it fits the spirit

Existing surfaces should be extended where appropriate, provided the extension does not substantially change the spirit of the surface.

For example, adding new target query types to tailscale ip is a good fit where those targets are sufficiently visible to clients: it is the same operation ("resolve a thing to an IP") applied to more inputs. That is extension in the spirit of the command, not scope creep.

Avoid arbitrary growth in complexity

Resist the temptation to grow a command to match the full surface of some external tool it resembles. For example, tailscale ssh does not intend to reimplement the full flag surface of ssh over time. Doing so would be an enormous and open-ended maintenance burden, and ssh itself is essentially ubiquitously available and already serves that purpose. A Tailscale command should do its job well, not absorb an entire adjacent ecosystem.

Debug commands

Heavily used debug subcommands should, over time, graduate into proper features of the main program when they prove broadly useful.

debug subcommands are explicitly not subject to our usual compatibility promises. They are best-effort and may change or be removed. Treat them as a staging ground and a power-user/diagnostic surface, not as a stable API. If a debug command becomes load-bearing for users, that is a signal to promote and stabilize it deliberately rather than to quietly grant it stability by neglect.

Configuration: where settings live

Profile-local preferences are the default home

Most configuration should be profile-local preferences, set and read via set/get, and modifiable at runtime. This is where the overwhelming majority of user-facing configuration belongs.

tailscaled flags are a last resort

Daemon (tailscaled) command-line flags should ideally be added only when a setting is truly process-global and immutable after launch. If something can reasonably be a profile-local preference that is changeable via set/get, it should be, not a daemon flag.

Daemon flags are sticky and global; they are the wrong place for anything a user might want to change per-profile or at runtime.

Daemon flags are also, in practice, almost Linux-only. Most GUI platforms (for example macOS, Windows, and mobile) make it very difficult for a user to adjust how the tailscale backend (e.g. tailscaled) is launched, so a setting that lives only in a daemon flag is effectively unreachable for most of our users. This is another reason to prefer profile-local preferences via set/get, which work uniformly across platforms.

Prefer preferences over environment variables

For both tailscale and tailscaled configuration surfaces, prefer preferences (set/get) over environment variables. Environment variables are hard to discover, hard to deprecate, and tend to leak into permanence.

TS_DEBUG environment knobs

Add TS_DEBUG-style env knobs freely as development work requires them. These are explicitly for development only. They are not intended for end users and should not be documented or encouraged for public use.

A cautionary note: we already have cases of debug env knobs that became load-bearing for someone and which we may never be able to remove. That is an undesirable outcome. Keeping these clearly internal and undocumented is what preserves our freedom to change or delete them.

Output and streams

--json and stable machine output

Commands should offer a stable JSON format behind a --json flag. Once a feature is generally available (GA), that JSON format is maintained in a backward-compatible way as much as possible, in keeping with Tailscale's broad compatibility policy.

Backward compatibility here means existing fields keep their meaning. Adding new fields is allowed and expected; consumers must tolerate unknown fields.

Human-readable (non-JSON) output

Non-JSON command output is the default and should be optimized, first and foremost, for easy reading by sighted humans, and, where possible, to read well with a screen reader. Concretely:

• Avoid decorative Unicode output. Prefer plain ASCII.
• Convey information in the text, not only via color or position. Do not rely on color to communicate meaning (see "Color and decoration" below).
• Keep output uncluttered and scannable.

The grep/awk-ability of stdout output should be considered and maintained on a best-effort basis, but it is not a hard compatibility guarantee when readability or usability would suffer substantially as a result.

In practice this means being conservative with the shape of stable output. For example:

• Adding a new column in the middle of already-stable tabular output should only be done after strongly weighing the tradeoffs, and most often should not be done, because it breaks naive positional parsers.
• Adding new in-column behavior can be done with care. A good example: the idle/connected/DERP/relay status field was extended to describe relays within the existing column rather than by adding a new column. That technically introduced new parsable content into the column (so the strictest parsers might notice), but it avoided breaking the common case, and not conveying the information would have been too large a usability and readability loss.

The principle: prefer changes that preserve the common parser and the human reader simultaneously; when forced to choose, protect the human reader, and make machine consumers use --json.

stdout vs. stderr

stderr is the standard information stream. It is not only for errors. It carries all informational, diagnostic, and progress output that is not the direct intended output of the command.

stdout should contain (within reason) the command's intended output — the thing the user actually asked for — or nothing. Everything else (status notes, progress, warnings, diagnostics) goes to stderr.

This separation is what makes the CLI usable in pipelines: a user can pipe stdout into another tool without having diagnostic chatter corrupt the data stream.

A couple of implications worth calling out:

• --help is intended output: when the user asks for help, help text should go to stdout.

• An error about bad flags that happens to print usage as part of a diagnostic message is diagnostic output and should go to stderr, not stdout.

  (At the time of writing, our handling of this distinction for help output is an existing bug. New code should follow the correct behavior, and we should fix the existing behavior over time.)

TTY-dependent behavior

Altering behavior based on whether stdout is a TTY is sometimes genuinely helpful (for example, suppressing a spinner when not interactive). Use it sparingly.

Major changes in behavior or output based on TTY detection are an impediment to use and should not be added arbitrarily. Requiring something like tailscale foo | less in order to discover a behavior should not become a standard pattern: it is a usability issue that excludes many users, including those using screen readers and automation.

Color and decoration

Support for, and further discussion of, colored or heavily decorated output is deferred at this time and should not be added until guidance is clarified.

The primary concern is accessibility: colored and decorated output is often hostile to screen-reader users, and information encoded only in color is invisible to many people. Until we have clear guidance, keep output plain and ensure all meaning is present in the text itself.

Summary checklist

When adding or changing CLI surface, ask:

• Tailscalars can raise a thread in #cli
• Could this be a profile-local preference via set/get instead of a new top-level command, a up flag, a daemon flag, or an env var? Usually it should be.
• Does it fit a tailscale <noun> <verb> shape without being awkward?
• Is the noun singular (unless that's strongly unnatural)?
• Does it provide stable --json output, and is the human output plain, screen-reader-friendly, and free of color-only meaning?
• Does intended output go to stdout and everything else to stderr?
• Are you extending an existing surface in its spirit, rather than growing complexity arbitrarily?
• If it's a debug command, is it clearly best-effort and not silently becoming a stable dependency?