Adds more documentation and automation guides.

README.md

@@ -15,11 +15,14 @@ A fast, cross-platform CLI tool and desktop GUI application for uploading files
 - 👥 **Multi-Account Support**: Configure and switch between multiple Nextcloud accounts or self-hosted instances seamlessly across CLI and GUI.
 - 🖥️ **Modern Desktop GUI**: Drag-and-drop queue management, per-file & total progress bars, retry handling, and browser-based Login Flow v2.
 - 🤖 **Automation Ready**: Output formatting options (`--json`, `--tsv`, `--url-only`, `--direct-url-only`) and headless SSH / CI authentication.
+- 🐚 **Shell Completions**: First-class completion scripts for `bash`, `zsh`, `fish`, `powershell`, and `elvish`.
 
 ---
 
 ## Documentation
 
+- 📖 **[CLI Reference](docs/cli-reference.md)**: Full syntax, subcommands (`login`, `upload`, `accounts`, `completions`), and options reference.
+- 💡 **[Automation & Scripting Recipes](docs/automation-recipes.md)**: Real-world examples for pipelines (`stdin`, `pv`, `mysqldump`, `curl`), `jq` parsing, and CI/CD workflows.
 - 📦 **[Installation Guide](docs/installation.md)**: Pre-built binaries, packages (`.dmg`, `.deb`, `.rpm`, `.msi`, `.AppImage`), and source compilation instructions.
 - 🖥️ **[GUI User Guide](docs/gui-guide.md)**: Walkthrough of the desktop app, drag-and-drop queue, retry mechanics, and account management.
 - 👥 **[Multi-Account Guide](docs/multi-account.md)**: Managing multiple servers, switching active defaults, and CLI/GUI token sharing.
@@ -36,10 +39,13 @@ A fast, cross-platform CLI tool and desktop GUI application for uploading files
 # Interactive Login Flow v2 (opens browser):
 nut login https://cloud.example.com --label "Work"
 
+# Headless SSH authorization (prints URL in terminal):
+nut login https://cloud.example.com --no-browser --label "Server"
+
 # Or connect interactively via terminal prompt:
 nut login https://cloud.example.com --manual
 
-# Or non-interactive / automated script:
+# Or non-interactive / CI automated script:
 nut login https://cloud.example.com -u alice -p "app-password"
 ```
 
@@ -61,6 +67,12 @@ tar -czf - data/ | nut upload -s --stdin --filename "backup.tar.gz"
 nut upload -s --url-only report.pdf | pbcopy
 ```
 
+#### Shell Completions:
+```bash
+# Generate shell completions (e.g. Zsh)
+nut completions zsh > ~/.zfunc/_nut
+```
+
 #### Manage multiple accounts:
 ```bash
 # List all accounts:

Tasks.md

@@ -71,7 +71,6 @@ This document defines the complete project roadmap and task tracking system for
 | ID | Title | Status | Type |
 |---|---|---|---|
 | [NUT-019](#nut-019) | Implement Homebrew/Winget/Chocolatey Manifests | Triage | Chore |
-| [NUT-023](#nut-023) | Write Comprehensive CLI Documentation and Automation Guides | Triage | Chore |
 | [NUT-024](#nut-024) | Create Docker/Podman Nextcloud Integration Test Harness | Triage | Foundation |
 | [NUT-001](#nut-001) | Establish Repository Structure | Fixed | Foundation |
 | [NUT-002](#nut-002) | Implement Shared Rust Backend Library | Fixed | Foundation |
@@ -94,6 +93,7 @@ This document defines the complete project roadmap and task tracking system for
 | [NUT-020](#nut-020) | Write Documentation + Examples | Fixed | Chore |
 | [NUT-021](#nut-021) | Support Headless & SSH Remote Authentication Modes | Fixed | Feature |
 | [NUT-022](#nut-022) | Implement CLI Shell Completions Generation | Fixed | Feature |
+| [NUT-023](#nut-023) | Write Comprehensive CLI Documentation and Automation Guides | Fixed | Chore |
 
 ---
 
@@ -541,20 +541,20 @@ Add automated shell completion script generation using `clap_complete` for major
 - NUT-008
 
 
-<a id="nut-023" class="task" data-status="triage" data-task-type="chore"></a>
+<a id="nut-023" class="task" data-status="done" data-task-type="chore"></a>
 ### Write Comprehensive CLI Documentation and Automation Guides  
 **ID:** NUT-023  
-**Status:** Triage  
+**Status:** Fixed  
 **Type:** Chore  
 
 **Description:**  
 Write dedicated CLI reference documentation and practical automation guides for scripting, CI/CD, and Unix pipeline workflows.
 
 **Requirements:**  
-- [ ] Document all CLI subcommands (`login`, `upload`, `accounts`, `completions`) and flags in `README.md`  
+- [x] Document all CLI subcommands (`login`, `upload`, `accounts`, `completions`) and flags in `README.md`  
-- [ ] Provide practical recipes for piping data (`stdin`, `pv`, `curl`, `mysqldump`)  
+- [x] Provide practical recipes for piping data (`stdin`, `pv`, `curl`, `mysqldump`)  
-- [ ] Provide scripting examples parsing `--json`, `--tsv`, `--url-only`, and `--direct-url-only` with `jq` and `xargs`  
+- [x] Provide scripting examples parsing `--json`, `--tsv`, `--url-only`, and `--direct-url-only` with `jq` and `xargs`  
-- [ ] Document headless SSH and CI/CD automated provisioning with `--username` and `--app-password`  
+- [x] Document headless SSH and CI/CD automated provisioning with `--username` and `--app-password`  
 
 **Dependencies:**  
 - NUT-008  

docs/automation-recipes.md

@@ -0,0 +1,131 @@
+# CLI Automation & Scripting Recipes
+
+This guide contains practical recipes for integrating `nut` into bash scripts, Unix pipelines, CI/CD runners, and headless server environments.
+
+---
+
+## 1. Piping Streams & Backups
+
+### Piping Database Backups Directly to Nextcloud
+Stream database dumps straight to Nextcloud without creating intermediate local files:
+
+```bash
+# MySQL / MariaDB Dump
+mysqldump -u root -p mydb | gzip -9 | \
+  nut upload -d "Backups/MySQL" --stdin --filename "mydb-$(date +%Y%m%d).sql.gz"
+
+# PostgreSQL Dump
+pg_dump mydb | zstd | \
+  nut upload -d "Backups/Postgres" --stdin --filename "mydb-$(date +%Y%m%d).sql.zst"
+```
+
+### Piping Compressed Archives with `pv` Rate Metering
+```bash
+# Compress and stream with live throughput monitoring
+tar -czf - /var/log/nginx | pv | \
+  nut upload -d "Backups/Logs" --stdin --filename "nginx-logs-$(date +%F).tar.gz"
+```
+
+### Piping from `curl` / `wget`
+Download a remote file and forward it to Nextcloud in one pipeline:
+```bash
+curl -fsSL https://example.com/large-dataset.csv.gz | \
+  nut upload -s -d "Datasets" --stdin --filename "large-dataset.csv.gz"
+```
+
+---
+
+## 2. Scripting with `jq`, `xargs`, and Clipboard
+
+### Uploading and Instant Clipboard Copy (macOS, Linux, Windows)
+```bash
+# macOS
+nut upload -s --url-only screenshot.png | pbcopy
+
+# Linux (X11 / Wayland)
+nut upload -s --url-only screenshot.png | xclip -selection clipboard
+# or wl-copy
+nut upload -s --url-only screenshot.png | wl-copy
+
+# Windows PowerShell
+nut upload -s --url-only screenshot.png | Set-Clipboard
+```
+
+### Batch Processing with `xargs`
+Upload all modified markdown files found with `find`:
+```bash
+find ./notes -name "*.md" -mtime -1 -print0 | \
+  xargs -0 nut upload -s -d "Notes/Daily" --json
+```
+
+### Extracting Links and Metadata with `jq`
+```bash
+# Extract all public share URLs into a text list
+nut upload -s -r assets/ --json | jq -r '.[].share_url // empty' > links.txt
+
+# Query direct download links
+nut upload -s build/*.pkg --json | jq -r '.[] | select(.success == true) | "\(.file): \(.direct_download_url)"'
+```
+
+### Scripting with TSV
+Parse tabular output in bash loops:
+```bash
+nut upload -s -r photos/ --tsv | while IFS=$'\t' read -r file remote bytes success share direct; do
+  if [ "$success" = "true" ]; then
+    echo "Uploaded $file ($bytes bytes) -> $share"
+  else
+    echo "Failed to upload $file"
+  fi
+done
+```
+
+---
+
+## 3. CI/CD & Headless Automation
+
+### Non-Interactive CI / GitHub Actions Setup
+Authenticate non-interactively using environment secrets in CI pipelines:
+
+```yaml
+name: Deploy Build Artifacts
+on: [push]
+
+jobs:
+  upload:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install nut
+        run: |
+          curl -fsSL https://github.com/majinnaibu/nextcloud-upload-tool/releases/latest/download/nut-x86_64-unknown-linux-musl.tar.gz | tar -xz
+          sudo mv nut /usr/local/bin/
+
+      - name: Authenticate Nextcloud
+        env:
+          NC_SERVER: ${{ secrets.NEXTCLOUD_SERVER_URL }}
+          NC_USER: ${{ secrets.NEXTCLOUD_USERNAME }}
+          NC_PASS: ${{ secrets.NEXTCLOUD_APP_PASSWORD }}
+        run: |
+          nut login "$NC_SERVER" -u "$NC_USER" -p "$NC_PASS" --label "CI"
+
+      - name: Build and Upload Artifact
+        run: |
+          tar -czf release-build.tar.gz dist/
+          SHARE_URL=$(nut upload -s --account "CI" --url-only release-build.tar.gz)
+          echo "Download link: $SHARE_URL"
+```
+
+### Headless SSH Remote Server Authorization
+When working over an SSH connection without X11 or desktop forwarding:
+
+```bash
+# Run login in headless mode
+nut login https://cloud.example.com --no-browser --label "ProductionServer"
+
+# nut prints:
+# ==> Please authorize access in your browser:
+#     https://cloud.example.com/index.php/login/v2/flow/abc123xyz
+# ==> Waiting for browser authorization...
+
+# Open that link on your local computer, authorize, and nut immediately captures the token!
+```

docs/cli-reference.md

@@ -0,0 +1,165 @@
+# Nextcloud Upload Tool (`nut`) — CLI Reference
+
+The `nut` CLI provides a fast, pipe-friendly command-line interface for interacting with Nextcloud instances.
+
+---
+
+## Command Syntax
+
+```bash
+nut <COMMAND> [OPTIONS]
+```
+
+### Global Flags
+- `-h`, `--help`: Print help documentation.
+- `-V`, `--version`: Print version information.
+
+---
+
+## 1. `nut login`
+
+Authenticates and saves a Nextcloud instance account into your operating system's native keychain.
+
+```bash
+nut login <SERVER_URL> [OPTIONS]
+```
+
+### Arguments
+- `<SERVER_URL>`: The base URL of the Nextcloud instance (e.g. `https://cloud.example.com` or `http://localhost:8080/nextcloud`).
+
+### Options
+- `--label <LABEL>`: Optional friendly name for this account (e.g. `Work`, `Personal`, `Staging`).
+- `--default <BOOL>`: Mark this account as the default active account (default: `true`).
+- `--no-browser`: Do not attempt to launch a local browser. Prints the Login Flow v2 URL to stdout for copy-pasting (ideal for SSH sessions).
+- `-m`, `--manual`: Interactively prompts for username and app password/token via terminal inputs.
+- `-u`, `--username <USER>`: Username for non-interactive / automated login (requires `-p` / `--app-password`).
+- `-p`, `--app-password <PASS>`: App password or token for non-interactive login (requires `-u` / `--username`).
+
+### Examples
+```bash
+# Interactive browser authorization (default)
+nut login https://cloud.example.com --label "Personal"
+
+# Headless SSH authorization
+nut login https://cloud.example.com --no-browser --label "Server-Backup"
+
+# Interactive terminal credential entry
+nut login https://cloud.example.com --manual
+
+# Automated non-interactive CI / container provisioning
+nut login https://cloud.example.com -u ci-bot -p "xxxx-xxxx-xxxx-xxxx" --label "CI"
+```
+
+---
+
+## 2. `nut upload`
+
+Uploads one or more files, folders, or standard input streams to Nextcloud with optional public share generation.
+
+```bash
+nut upload [FILE]... [OPTIONS]
+```
+
+### Arguments
+- `[FILE]...`: One or more local file or directory paths to upload.
+
+### Options
+- `-a`, `--account <ACCOUNT>`: Override default account with a specific account ID or label.
+- `-d`, `--remote-dir <DIR>`: Destination directory on Nextcloud (default: `Uploads`).
+- `-s`, `--share`: Automatically create a public share link after upload.
+- `--password <PASSWORD>`: Set a password for the generated public share link.
+- `-r`, `--recursive`: Recursively upload directories and nested directory hierarchies.
+- `-c`, `--continue-on-error`: Continue processing remaining files if one fails.
+- `--no-progress`: Disable progress bars even when running in an interactive TTY.
+- `--stdin`: Upload standard input data stream.
+- `--filename <NAME>`: Remote filename to use when uploading via `--stdin` (default: `stdin_upload.txt`).
+- `--size <BYTES>`: Expected size in bytes for stdin streams (enables ETA and progress bar).
+
+### Formatting Options
+- `--json`: Output machine-readable JSON (array for batches, object for single file).
+- `--tsv`: Output Tab-Separated Values (file, remote path, bytes, success, share URL, direct URL).
+- `--url-only`: Output only the public share URL (requires `--share`).
+- `--direct-url-only`: Output only the direct download URL (requires `--share`).
+- `-q`, `--quiet`: Suppress progress output and print only share links or uploaded paths.
+
+### Examples
+```bash
+# Upload a single file with public share link
+nut upload -s report.pdf
+
+# Upload multiple files into a remote folder
+nut upload -s -d "Documents/2026" sheet1.xlsx sheet2.xlsx
+
+# Recursive directory upload
+nut upload -s -r assets/
+
+# Upload standard input stream with custom filename
+cat database.sql | nut upload -s --stdin --filename "database.sql"
+
+# Upload and copy public share URL directly to clipboard
+nut upload -s --url-only image.png | pbcopy
+```
+
+---
+
+## 3. `nut accounts` / `nut account`
+
+Manage stored Nextcloud accounts and configure default active accounts.
+
+### `nut accounts` / `nut account list`
+List all stored accounts and their status.
+```bash
+nut accounts
+nut accounts --json
+nut accounts --tsv
+```
+
+### `nut account default <ACCOUNT>`
+Set the active default account by ID or friendly label.
+```bash
+nut account default Work
+nut account default alice@cloud.example.com
+```
+
+### `nut account delete <ACCOUNT>`
+Remove an account and wipe its token from the OS keychain.
+```bash
+nut account delete "Personal"
+```
+
+---
+
+## 4. `nut completions`
+
+Generates shell completion scripts for your preferred shell environment.
+
+```bash
+nut completions <SHELL>
+```
+
+### Supported Shells
+- `bash`
+- `zsh`
+- `fish`
+- `powershell`
+- `elvish`
+
+### Installation Examples
+```bash
+# Zsh
+nut completions zsh > ~/.zfunc/_nut
+
+# Bash
+nut completions bash > /etc/bash_completion.d/nut
+# Or load in ~/.bashrc:
+source <(nut completions bash)
+
+# Fish
+nut completions fish > ~/.config/fish/completions/nut.fish
+
+# PowerShell
+nut completions powershell >> $PROFILE
+
+# Elvish
+nut completions elvish > ~/.elvish/lib/nut.elv
+```