diff --git a/README.md b/README.md index 49e09ce..ee8f0c2 100644 --- a/README.md +++ b/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: diff --git a/Tasks.md b/Tasks.md index 0b04f67..6399100 100644 --- a/Tasks.md +++ b/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 - + ### 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` -- [ ] 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` -- [ ] Document headless SSH and CI/CD automated provisioning with `--username` and `--app-password` +- [x] Document all CLI subcommands (`login`, `upload`, `accounts`, `completions`) and flags in `README.md` +- [x] Provide practical recipes for piping data (`stdin`, `pv`, `curl`, `mysqldump`) +- [x] Provide scripting examples parsing `--json`, `--tsv`, `--url-only`, and `--direct-url-only` with `jq` and `xargs` +- [x] Document headless SSH and CI/CD automated provisioning with `--username` and `--app-password` **Dependencies:** - NUT-008 diff --git a/docs/automation-recipes.md b/docs/automation-recipes.md new file mode 100644 index 0000000..f6d1357 --- /dev/null +++ b/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! +``` diff --git a/docs/cli-reference.md b/docs/cli-reference.md new file mode 100644 index 0000000..1e40172 --- /dev/null +++ b/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 [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 [OPTIONS] +``` + +### Arguments +- ``: The base URL of the Nextcloud instance (e.g. `https://cloud.example.com` or `http://localhost:8080/nextcloud`). + +### Options +- `--label