Adds comprehensive documentation.
This commit is contained in:
123
README.md
123
README.md
@@ -1,68 +1,101 @@
|
||||
# Nextcloud Upload Tool (`nut`)
|
||||
|
||||
[](https://github.com/majinnaibu/nextcloud-upload-tool/actions/workflows/ci.yml)
|
||||
[](LICENSE)
|
||||
|
||||
A fast, cross-platform CLI tool and desktop GUI application for uploading files to Nextcloud and instantly generating direct download / public share links.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
## Key Features
|
||||
|
||||
**Nextcloud Upload Tool** is designed for quick terminal workflows and smooth desktop integration. It allows you to pipe or upload files directly to your Nextcloud instance, securely manage credentials via your OS keychain, and immediately copy shareable links.
|
||||
|
||||
### Key Features
|
||||
|
||||
- ⚡ **High-Performance Uploads**: WebDAV streaming uploads with real-time progress reporting and pipe support (`stdin`, `pv`).
|
||||
- 🔗 **Instant Share Links**: Direct integration with Nextcloud's OCS Sharing API to generate public share URLs and direct-download links.
|
||||
- ⚡ **High-Performance Uploads**: WebDAV streaming uploads with real-time progress reporting and pipe support (`stdin`, `pv`, Unix pipelines).
|
||||
- 🔗 **Instant Share Links**: Direct integration with Nextcloud's OCS Sharing API to generate public share URLs and direct-download links with optional password protection.
|
||||
- 🔐 **Secure Credential Storage**: Native OS Keychain integration (macOS Keychain, Windows Credential Manager, Linux Secret Service) with encrypted file fallback.
|
||||
- 👥 **Multi-Account Support**: Configure and switch between multiple Nextcloud accounts or self-hosted instances seamlessly.
|
||||
- 🖥️ **CLI & GUI Frontends**: A lightweight terminal binary (`nut`) and a modern desktop application powered by Tauri.
|
||||
- 👥 **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.
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
- 📦 **[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.
|
||||
- 🏗️ **[Architecture & Developer Guide](docs/architecture.md)**: Workspace layout, WebDAV/OCS protocol implementation, and Tauri IPC bridge.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. CLI Usage
|
||||
|
||||
#### Connect your Nextcloud account:
|
||||
```bash
|
||||
# Interactive Login Flow v2 (opens browser):
|
||||
nut login https://cloud.example.com --label "Work"
|
||||
|
||||
# Or connect interactively via terminal prompt:
|
||||
nut login https://cloud.example.com --manual
|
||||
|
||||
# Or non-interactive / automated script:
|
||||
nut login https://cloud.example.com -u alice -p "app-password"
|
||||
```
|
||||
|
||||
#### Upload files and generate share links:
|
||||
```bash
|
||||
# Upload a single file and generate a public share link:
|
||||
nut upload -s document.pdf
|
||||
|
||||
# Upload multiple files into a remote folder:
|
||||
nut upload -s -d "Projects/2026" file1.png file2.png
|
||||
|
||||
# Upload recursively:
|
||||
nut upload -s -r assets/
|
||||
|
||||
# Stream from standard input (e.g. backup pipes):
|
||||
tar -czf - data/ | nut upload -s --stdin --filename "backup.tar.gz"
|
||||
|
||||
# Output only the share link (ideal for scripts and clipboard pipes):
|
||||
nut upload -s --url-only report.pdf | pbcopy
|
||||
```
|
||||
|
||||
#### Manage multiple accounts:
|
||||
```bash
|
||||
# List all accounts:
|
||||
nut accounts
|
||||
|
||||
# Switch default active account:
|
||||
nut account default "Work"
|
||||
|
||||
# Upload to a specific account:
|
||||
nut upload --account "Personal" photo.jpg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. GUI Usage
|
||||
|
||||
Launch the desktop app via `nut-gui` or from your system applications menu. Drag and drop any files into the window, configure your remote destination folder, toggle public share link creation, and click **Upload All**.
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
This repository is structured as a Cargo workspace:
|
||||
|
||||
```
|
||||
.
|
||||
├── nextcloud_client/ # Core Rust backend library (WebDAV, OCS API, Keyring, Config)
|
||||
├── cli/ # Terminal CLI executable (`nut`)
|
||||
├── gui/ # Desktop GUI application (Tauri + Web frontend)
|
||||
├── Tasks.md # Canonical project roadmap and task tracking
|
||||
├── nextcloud_client/ # Core Rust backend library (WebDAV, OCS API, Keyring, Config)
|
||||
├── cli/ # Terminal CLI executable (`nut`)
|
||||
├── gui/ # Desktop GUI application (Tauri v2 + React frontend)
|
||||
├── docs/ # Detailed guides and developer documentation
|
||||
├── scripts/ # Packaging and build helper scripts
|
||||
├── Tasks.md # Canonical project roadmap and task tracking
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [Rust](https://www.rust-lang.org/) (1.75+ recommended)
|
||||
- A running [Nextcloud](https://nextcloud.com/) instance with WebDAV and sharing enabled
|
||||
|
||||
### Building the Workspace
|
||||
|
||||
Clone the repository and build the workspace crates:
|
||||
|
||||
```bash
|
||||
# Build all workspace members
|
||||
cargo build
|
||||
|
||||
# Run the CLI tool
|
||||
cargo run -p nut -- --help
|
||||
|
||||
# Run tests
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Roadmap & Tasks
|
||||
|
||||
Project tasks, feature specifications, and current progress are tracked in [Tasks.md](Tasks.md).
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the [MIT License](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user