docs: add eggl-cli documentation site

.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Setup Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6
+
+      - name: Upload artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
+        with:
+          path: doc_build
+
+  deploy:
+    name: Deploy
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-24.04
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: https://cli.eggl.dev
+    steps:
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5

.gitignore

@@ -1,6 +1,8 @@
 # Build output
 /bin/
 /dist/
+/doc_build/
+node_modules/
 eggl
 eggl-*
 

.goreleaser.yaml

@@ -56,7 +56,7 @@ brews:
       name: homebrew-tap
       branch: main
       token: "{{ .Env.TAP_GITHUB_TOKEN }}"
-    homepage: "https://github.com/roberteggl/eggl-cli"
+    homepage: "https://cli.eggl.dev"
     description: "General-purpose helper CLI"
     license: "MIT"
     commit_author:

README.md

@@ -6,7 +6,7 @@
 [![Go](https://img.shields.io/github/go-mod/go-version/roberteggl/eggl-cli?style=flat-square)](https://go.dev/)
 [![License](https://img.shields.io/github/license/roberteggl/eggl-cli?style=flat-square)](LICENSE)
 
-A general-purpose helper CLI built with Go and [Cobra](https://github.com/spf13/cobra).
+eggl-cli is a general-purpose helper built with Go and [Cobra](https://github.com/spf13/cobra).
 
 ## Install
 
@@ -133,3 +133,5 @@ eggl completion fish > ~/.config/fish/completions/eggl.fish
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project layout, and release instructions.
+
+Built by [Robert Eggl](https://eggl.dev).

docs/_meta.json

@@ -0,0 +1,41 @@
+[
+  {
+    "type": "section-header",
+    "label": "Getting started"
+  },
+  "install",
+  "quickstart",
+  "completion",
+  {
+    "type": "divider"
+  },
+  {
+    "type": "section-header",
+    "label": "Configuration"
+  },
+  {
+    "type": "dir",
+    "name": "configuration",
+    "label": "Configuration"
+  },
+  {
+    "type": "section-header",
+    "label": "Commands"
+  },
+  {
+    "type": "dir",
+    "name": "commands",
+    "label": "Command reference"
+  },
+  {
+    "type": "divider"
+  },
+  {
+    "type": "section-header",
+    "label": "Reference"
+  },
+  "workflows",
+  "troubleshooting",
+  "development",
+  "releasing"
+]

docs/commands/_meta.json

@@ -0,0 +1,10 @@
+[
+  "index",
+  "env",
+  "pf",
+  "cd",
+  "text-files",
+  "kill",
+  "empty",
+  "diagnostics"
+]

docs/commands/cd.md

@@ -0,0 +1,15 @@
+# `eggl cd`
+
+Resolve a configured directory alias and print its path.
+
+```bash
+cd "$(eggl cd homelab)"
+```
+
+## Flags
+
+| Flag | Description |
+| --- | --- |
+| `--config <path>` | Use a specific config file |
+
+The `eggl cd` command does not change the caller's working directory because child processes cannot modify the parent shell. Use command substitution or the `egglcd` shell function shown in [Directory aliases](/configuration/directories).

docs/commands/diagnostics.md

@@ -0,0 +1,33 @@
+# Diagnostics and Metadata
+
+## `eggl doctor`
+
+Run sanity checks for the local environment:
+
+```bash
+eggl doctor
+eggl doctor --verbose
+eggl doctor --check-path /tmp
+```
+
+The checks cover the Go runtime, platform, home directory, `kubectl`, Git, Tailscale, and config validity when a config file exists. The command exits non-zero if any check fails.
+
+## `eggl version`
+
+```bash
+eggl version
+eggl version --short
+```
+
+The full output includes the installed version, commit, and build date. `--short` prints only the version string for scripts.
+
+## `eggl completion`
+
+Generate Bash, Zsh, Fish, or PowerShell completion scripts:
+
+```bash
+eggl completion zsh
+eggl completion bash
+```
+
+See [Shell completion](/completion) for installation instructions.

docs/commands/empty.md

@@ -0,0 +1,15 @@
+# `eggl empty`
+
+Create an empty Git commit. This is useful for retriggering a CI pipeline without changing tracked files.
+
+```bash
+eggl empty
+eggl empty --push
+eggl empty -p
+```
+
+| Flag | Description |
+| --- | --- |
+| `-p, --push` | Push the new commit after creating it |
+
+The command runs in the current repository and reports the commit hash. With `--push`, the configured Git remote and credentials are used.

docs/commands/env.md

@@ -0,0 +1,26 @@
+# `eggl env`
+
+Switch a Kubernetes context and Tailscale account as one named environment.
+
+```bash
+eggl env init
+eggl env show
+eggl env use homelab
+eggl env toggle
+```
+
+## Subcommands
+
+| Command | Description |
+| --- | --- |
+| `init` | Create an example config file if one does not exist |
+| `show` | Show active profile and current state |
+| `use <profile>` | Apply a named profile |
+| `toggle` | Flip between exactly two profiles |
+| `path` | Print the resolved config path |
+
+## Flags
+
+`env` has a persistent `--config <path>` flag. It applies to all subcommands and overrides the default config path.
+
+`toggle` requires exactly two profiles. `use` is the explicit option when there are more than two profiles or when the current state is not recognized.

docs/commands/index.md

@@ -0,0 +1,28 @@
+# Command Reference
+
+Run `eggl --help` for the top-level list or `eggl <command> --help` for the flags and examples for a command. The executable is `eggl`; the product is eggl-cli.
+
+| Command | Purpose | External dependency |
+| --- | --- | --- |
+| `env` | Switch paired Kubernetes and Tailscale profiles | `kubectl`, `tailscale` |
+| `pf` | Run named Kubernetes port-forwards | `kubectl` |
+| `cd` | Resolve configured directory aliases | None |
+| `dedash` | Replace em-dashes in text files | Optional Git integration |
+| `eol` | Normalize text files to LF | Optional Git integration |
+| `kill` | Find and terminate processes on a TCP port | OS process tools |
+| `empty` | Create an empty Git commit | `git` |
+| `doctor` | Check local tools and paths | Checks available tools |
+| `version` | Print build information | None |
+| `completion` | Generate shell completion scripts | None |
+
+All eggl-cli commands support the global `--verbose` flag. It sends operation details to stderr. Set `NO_COLOR` to disable interactive styling.
+
+## Command groups
+
+- [Environment profiles](/commands/env)
+- [Kubernetes port-forwards](/commands/pf)
+- [Directory aliases](/commands/cd)
+- [Repository text files](/commands/text-files)
+- [Process cleanup](/commands/kill)
+- [Git automation](/commands/empty)
+- [Diagnostics and metadata](/commands/diagnostics)

docs/commands/kill.md

@@ -0,0 +1,19 @@
+# `eggl kill`
+
+Find processes listening on a local TCP port and terminate them.
+
+```bash
+eggl kill 8080
+eggl kill --dry-run 3000
+eggl kill --yes --force 8080
+```
+
+## Flags
+
+| Flag | Description |
+| --- | --- |
+| `--dry-run` | List matching processes without killing them |
+| `-y, --yes` | Skip the confirmation prompt |
+| `-f, --force` | Send `SIGKILL` instead of `SIGTERM` |
+
+Use `--dry-run` before `--force` when investigating a stale port-forward or development server. Without `--force`, eggl-cli requests graceful termination.

docs/commands/pf.md

@@ -0,0 +1,20 @@
+# `eggl pf`
+
+Run a configured Kubernetes port-forward using the active kubectl context.
+
+```bash
+eggl pf list
+eggl pf grafana
+eggl pf grafana --open
+```
+
+## Flags
+
+| Flag | Description |
+| --- | --- |
+| `--config <path>` | Use a specific config file |
+| `-o, --open` | Open `http://localhost:<port>` after the tunnel is ready |
+
+`eggl pf list` prints configured names, namespaces, resources, and ports. Calling `eggl pf` without a service prints command help.
+
+The service argument supports shell completion from the names in the config file.

docs/commands/text-files.md

@@ -0,0 +1,37 @@
+# `eggl dedash` and `eggl eol`
+
+Both commands recursively scan text files and provide the same safety controls.
+
+| Command | Change |
+| --- | --- |
+| `eggl dedash` | Replace Unicode em-dashes with ASCII hyphens |
+| `eggl eol` | Convert CRLF or CR line endings to LF |
+
+## Preview first
+
+```bash
+eggl dedash --dry-run
+eggl eol --dry-run
+```
+
+Without `--dry-run`, the command asks for confirmation before writing. Use `--yes` in automation or when stdin is not a terminal.
+
+## Scope controls
+
+```bash
+eggl dedash --path ./docs --ext md,txt --dry-run
+eggl eol --diff --dry-run
+eggl dedash --diff-base main --dry-run
+```
+
+| Flag | Description |
+| --- | --- |
+| `--path <dir>` | Directory tree to scan; defaults to `.` |
+| `--dry-run` | Report changes without writing |
+| `-y, --yes` | Skip the write confirmation |
+| `--ext <list>` | Limit processing to extensions such as `md,txt` |
+| `--include-hidden` | Include dotfiles and dot-directories |
+| `--diff` | Process staged or unstaged Git changes |
+| `--diff-base <ref>` | Process files changed since a Git ref |
+
+`--diff` and `--diff-base` are mutually exclusive. Binaries, common dependency directories, `.git`, and files larger than 50 MiB are skipped.

docs/completion.md

@@ -0,0 +1,45 @@
+# Shell Completion
+
+eggl-cli generates completion scripts for Bash, Zsh, Fish, and PowerShell.
+
+## Bash
+
+Load for the current session:
+
+```bash
+source <(eggl completion bash)
+```
+
+Persist it system-wide or in your shell configuration:
+
+```bash
+eggl completion bash > /etc/bash_completion.d/eggl
+```
+
+## Zsh
+
+```bash
+eggl completion zsh > "${fpath[1]}/_eggl"
+```
+
+Restart the shell or run `compinit` after writing the file.
+
+## Fish
+
+```bash
+eggl completion fish > ~/.config/fish/completions/eggl.fish
+```
+
+## PowerShell
+
+Load for the current session:
+
+```powershell
+eggl completion powershell | Out-String | Invoke-Expression
+```
+
+Write a script for later use:
+
+```powershell
+eggl completion powershell > eggl.ps1
+```