From 81720b985e4aedb02ba6fa5610c16cb77b53b5a8 Mon Sep 17 00:00:00 2001
From: Nightshift <contact+nightshift@micr.dev>
Date: Mon, 13 Apr 2026 20:05:27 +0000
Subject: [PATCH] docs: improve README with requirements, CLI flags, env vars,
 build instructions

- Add requirements section (elevated privileges, supported OS, Go version)
- Document all CLI flags for run, agent, cleanup, and gui subcommands
- Add environment variables section with common variable names
- Add building from source section with Makefile targets
- Note arm64 release binaries in platform support
- Fix stale PLAN.md link -> CONTRIBUTING.md link
- Fix lease modes description (remove hardcoded '1,3,7', reference --days/--custom-days)
- Add agent --once example
---
 README.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 103 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index c11b80b..a9b11a6 100644
--- a/README.md
+++ b/README.md
@@ -21,9 +21,16 @@
 
 if you need to get a field machine onto your tailnet without building a backend service around the process, tailstick gives you a controlled local workflow. it keeps the operator flow simple, supports session, timed, and permanent access, and keeps cleanup tied to the same lease record instead of spreading state across ad hoc scripts.
 
+## requirements
+
+- **elevated privileges** are required for enrollment and cleanup (`sudo` on linux, administrator on windows).
+- **linux**: debian or ubuntu with `systemd`. other distributions are not supported in the current release.
+- **windows**: standard windows with scheduled tasks available.
+- **go 1.22+** is required for building from source.
+
 ## quickstart
 
-1. go to [releases](https://github.com/Microck/tailstick/releases/latest) and download the binary you want for your machine. use the cli if you want a direct command flow, or use the gui if you want the local browser flow.
+1. go to [releases](https://github.com/Microck/tailstick/releases/latest) and download the binary you want for your machine. use the cli if you want a direct command flow, or use the gui if you want the local browser flow. binaries are available for `linux/amd64`, `linux/arm64`, `windows/amd64`, and `windows/arm64`.
 2. put that binary in a working folder, then place a `tailstick.config.json` file next to it.
 3. write that config by hand from `configs/tailstick.config.example.json`, or use the optional [preset maker](https://tailstick.micr.dev/) if you want a faster way to build it.
 4. make sure you have the secrets your presets depend on. in most setups that means a tailscale auth key, a tailscale ephemeral auth key, and a tailscale api key for cleanup. if you want password-gated operator use, you also need an operator password.
@@ -39,6 +46,8 @@ for normal operator use, use the release binaries. building from source is only
 | linux (debian/ubuntu + `systemd`) | supported | supported | supported |
 | windows | supported | supported | supported |
 
+release binaries are built for `linux/amd64`, `linux/arm64`, `windows/amd64`, and `windows/arm64`.
+
 ## command surface
 
 | command | purpose |
@@ -48,6 +57,61 @@ for normal operator use, use the release binaries. building from source is only
 | `tailstick cleanup` | force cleanup for one lease id |
 | `tailstick version` | print version |
 
+### `run` flags
+
+| flag | default | description |
+| --- | --- | --- |
+| `--preset` | `""` | preset id from config |
+| `--mode` | `session` | lease mode: `session`, `timed`, or `permanent` |
+| `--channel` | `stable` | install channel: `stable` or `latest` |
+| `--days` | `3` | timed lease duration in days |
+| `--custom-days` | `0` | custom lease days (1–30, overrides `--days`) |
+| `--suffix` | `""` | optional device name suffix |
+| `--exit-node` | `""` | optional approved exit node |
+| `--allow-existing` | `false` | allow existing tailscale install |
+| `--non-interactive` | `false` | non-interactive mode |
+| `--password` | `""` | operator password (or set `TAILSTICK_OPERATOR_PASSWORD`) |
+| `--config` | `tailstick.config.json` | config file path |
+| `--state` | platform default | state file path |
+| `--audit` | `logs/tailstick-audit.ndjson` | audit log path |
+| `--log` | platform default | log file path |
+| `--dry-run` | `false` | print commands without executing |
+
+### `agent` flags
+
+| flag | default | description |
+| --- | --- | --- |
+| `--once` | `false` | run one reconciliation pass and exit |
+| `--interval` | `1m` | reconciliation interval |
+
+the agent also accepts `--config`, `--state`, `--audit`, `--log`, and `--dry-run`.
+
+### `cleanup` flags
+
+| flag | default | description |
+| --- | --- | --- |
+| `--lease-id` | `""` | lease id to clean (required) |
+
+the cleanup command also accepts `--config`, `--state`, `--audit`, `--log`, and `--dry-run`.
+
+### gui flags
+
+the gui binary (`tailstick-linux-gui` / `tailstick-windows-gui`) starts a local browser-based setup wizard. in addition to the shared flags (`--config`, `--state`, `--audit`, `--log`, `--dry-run`):
+
+| flag | default | description |
+| --- | --- | --- |
+| `--host` | `127.0.0.1` | bind host |
+| `--port` | `0` | bind port (`0` picks an ephemeral port) |
+| `--open-browser` | `true` | open browser automatically |
+
+## lease modes
+
+| mode | behavior |
+| --- | --- |
+| `session` | cleaned after reboot/shutdown detection |
+| `timed` | cleaned when expiry is reached (set duration with `--days` or `--custom-days`) |
+| `permanent` | leaves normal tailscale install and no automatic cleanup |
+
 for lease modes, tailstick installs local scheduling:
 
 - linux: `tailstick-agent.service` + `tailstick-agent.timer`
@@ -58,13 +122,18 @@ the scheduled command runs from a machine-local binary copy:
 - linux: `/var/lib/tailstick/tailstick-agent`
 - windows: `%ProgramData%\TailStick\tailstick-agent.exe`
 
-## lease modes
+## environment variables
 
-| mode | behavior |
+secrets are resolved from environment variables. the config file supports `authKeyEnv`, `ephemeralAuthKeyEnv`, and `apiKeyEnv` fields that name the env var to read. common variables:
+
+| variable | purpose |
 | --- | --- |
-| `session` | cleaned after reboot/shutdown detection |
-| `timed` | cleaned when expiry is reached (`1`, `3`, `7`, or bounded custom days) |
-| `permanent` | leaves normal tailscale install and no automatic cleanup |
+| `TAILSTICK_AUTH_KEY` | tailscale auth key |
+| `TAILSTICK_EPHEMERAL_AUTH_KEY` | tailscale ephemeral auth key |
+| `TAILSTICK_API_KEY` | tailscale api key for cleanup |
+| `TAILSTICK_OPERATOR_PASSWORD` | operator password for gated presets |
+
+see `.env.example` for a template.
 
 ## examples
 
@@ -95,6 +164,33 @@ manual cleanup:
 ./tailstick-linux-cli cleanup --lease-id <lease-id>
 ```
 
+single agent pass:
+
+```bash
+./tailstick-linux-cli agent --once
+```
+
+## building from source
+
+```bash
+go build ./cmd/tailstick-linux-cli
+go build ./cmd/tailstick-linux-gui
+```
+
+cross-compile all targets:
+
+```bash
+make build-all
+```
+
+run tests:
+
+```bash
+go test ./...
+```
+
+see the `Makefile` for additional targets (`fmt`, `vet`, `sandbox-linux`, `icons`).
+
 ## documentation
 
 - [architecture](docs/architecture.md)
@@ -102,7 +198,7 @@ manual cleanup:
 - [operations](docs/operations.md)
 - [testing](docs/testing.md)
 - [release runbook](docs/release-runbook.md)
-- [plan](PLAN.md)
+- [contributing](CONTRIBUTING.md)
 
 ## license