Content
# GoQuark
[English](README.en.md) · English
<p align="center">
<img src="docs/banner.png" alt="GoQuark" width="480">
</p>
<p align="center">
<strong>Unofficial</strong> Quark Cloud Storage CLI / TUI / MCP Client
</p>
<p align="center">
Scan Code Login · High-Speed Download · Interactive Cloud Storage · Agent Friendly
</p>
<p align="center">
<img alt="version" src="https://img.shields.io/badge/version-1.0.1-blue">
<img alt="go" src="https://img.shields.io/badge/Go-1.22+-00ADD8?logo=go">
<img alt="license" src="https://img.shields.io/badge/license-AGPL--3.0-blue">
<img alt="platform" src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey">
</p>
---
## What is this?
GoQuark is a Quark Cloud Storage client written in **Go**, targeting command-line and automation scenarios:
| Scenario | Capability |
|------|------|
| Login | Quark APP **Scan Code Login** |
| Download | **Close to real client** download speed; queue, pause/resume, progress, and ETA |
| Browse | Terminal **TUI**: select, multi-select, right-click menu, download center |
| Script | CLI + pipeline / `--json` output |
| Agent | **MCP** (stdio), accessible to Claude Desktop, Cursor, etc. |
> **Unofficial project.** No affiliation, authorization, or cooperation with Quark, UC, Alibaba Group, or its affiliates.
> For learning and research purposes only; use at your own risk. See [Disclaimer](#disclaimer) and [DISCLAIMER.md](docs/DISCLAIMER.md).
---
## Feature List
- Scan code login, device information locally fixed, customizable name
- Multi-file download, download center, history records
- Pause / resume / cancel; safe exit
- Directory browsing, user information (`ls` / `whoami`)
- Terminal UI (supports mouse)
- MCP tool: device, user, list directory, download
- Version number injected by build (see [Version](#version))
<p align="center">
<img src="docs/screenshot-tui.png" alt="GoQuark TUI" width="820">
</p>
> ⭐ If this project helps you, consider starring it for support!
---
## Component Architecture
The entry points are **CLI / TUI / MCP**, sharing the same core library.
```mermaid
flowchart LR
CLI --> Core[Core Library]
TUI --> Core
MCP --> Core
Core --> Auth[Authentication]
Core --> Download[Download]
Core --> Config[Configuration]
Core --> Update[Update]
Core --> Output[Output]
```
| Module | Description |
|------|------|
| **CLI** | Command-line entry: login, list directory, download, update, etc. |
| **TUI** | Terminal interactive interface: browse, multi-select, download center |
| **MCP** | stdio tool, providing the same capabilities for agents |
| **Core Library** | Shared logic for authentication, download, configuration, update, output, etc. |
---
## Installation
**Recommended: one-click installation** (automatically fetch the corresponding binary from [GitHub Releases](https://github.com/ButterFuture/GoQuark/releases) without installing Go):
```bash
curl -fsSL https://raw.githubusercontent.com/ButterFuture/GoQuark/main/scripts/install.sh | bash
```
Default installation location: `~/.local/bin/goquark` (or `/usr/local/bin` if writable). Optional parameters:
```bash
# Specify version / directory
curl -fsSL https://raw.githubusercontent.com/ButterFuture/GoQuark/main/scripts/install.sh | bash -s -- --version v1.0.1
curl -fsSL https://raw.githubusercontent.com/ButterFuture/GoQuark/main/scripts/install.sh | bash -s -- --dir ~/.local/bin
```
**Or manually download Release:**
1. Open <https://github.com/ButterFuture/GoQuark/releases>
2. Select the system-specific file, e.g.:
- Linux x64 → `goquark_*_linux_amd64`
- Linux ARM64 → `goquark_*_linux_arm64`
- macOS Apple Silicon → `goquark_*_darwin_arm64`
- Windows → `goquark_*_windows_amd64.exe`
3. (Optional) Verify with `SHA256SUMS` in the same directory
4. `chmod +x goquark_*` and move to `PATH`, then rename to `goquark`
```bash
chmod +x goquark_1.0.1_linux_amd64
sudo mv goquark_1.0.1_linux_amd64 /usr/local/bin/goquark
```
After installation, **recommended to start TUI directly**:
```bash
goquark tui
```
Upgrade: re-run the installation script or use `goquark update --yes` (TUI also supports update checks).
<details>
<summary>Build from source (optional, requires Go toolchain)</summary>
See **[docs/BUILD.md](docs/BUILD.md)**.
</details>
---
## Quick Start
**Preferred: TUI** (browse, download, download center all in terminal)
```bash
goquark tui
```
First-time use will guide you through scan code login. For most operations, continue using TUI.
<details>
<summary>Command-line usage (scripting / automation)</summary>
```bash
goquark login # Scan code login (terminal output + qrcode.png)
goquark device # Device information
goquark whoami # Current user
goquark ls / # List directory
goquark download /cloud/path/file.mkv
goquark downloads # Task list
goquark downloads --watch
goquark mcp # MCP (stdio)
goquark version
```
</details>
| Configuration | Description |
|--------|------|
| Configuration file | `~/.config/goquark/config.json` |
| Override method | Environment variable `GOQUARK_CONFIG` or parameter `-config` |
| Default download directory | `~/Downloads/GoQuark` (can be overridden with `download_dir` / `GOQUARK_DOWNLOAD_DIR`) |
Login status and Cookie **stored locally only**. Do not submit configurations containing Cookie to Git or share with others.
---
## TUI Shortcuts (Summary)
| Key | Action |
|------|------|
| Click / Space | Select |
| `d` | Download selected |
| `t` | Download center |
| Right-click / `m` | Menu |
| `p` / `r` / `x` / `c` | Pause / resume / cancel / clear completed (in download center) |
| `q` | Exit (safe pause ongoing tasks after confirmation) |
---
## MCP
Provides services through **stdio**: host process starts `goquark mcp`.
1. Build and install to a fixed path
2. Run `goquark login` once
3. Fill in the **absolute path** in the host
### Claude Desktop
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"goquark": {
"command": "/path/to/goquark",
"args": ["mcp"]
}
}
}
```
### Cursor / Other stdio Hosts
```json
{
"mcpServers": {
"goquark": {
"command": "/path/to/goquark",
"args": ["mcp"]
}
}
}
```
| Tool | Description |
|------|------|
| `goquark_device` | Device information |
| `goquark_whoami` | Current user |
| `goquark_ls` | List directory (`path`, default `/`) |
| `goquark_download` | Download (`remote`, `local`) |
---
## Version
| Project | Description |
|------|------|
| Sole source | Repository root directory [`VERSION`](VERSION) (current **1.0.1**) |
| Build injection | `scripts/build.sh` / CI writes version into binary via `-ldflags` |
| Local `go run` | Displays `dev` when not injected |
```bash
./scripts/version.sh # Print version
./scripts/build.sh # Build with version
goquark version # View injected version
```
Release suggestions: improve functionality → confirm → update `VERSION` → tag `v1.0.1` → CI / Release.
---
## Tech Stack
| Layer | Selection |
|------|------|
| Language | Go |
| TUI | Bubble Tea, Lip Gloss |
| Network | Go `net/http`, TLS |
| Agent | MCP (stdio) |
| Configuration | JSON (`~/.config/goquark/`) |
Download side uses multi-connection HTTP and local task management (queue, pause/resume, progress UI), aiming for **download speed close to real clients**.
---
## License
Original code in this repository is licensed under **[GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE)**.
- **Require copyright and license statement** (attribution)
- **Copyleft**: modified versions providing services (including network services) or distribution must provide corresponding source code under AGPL-3.0
- Third-party dependencies have their respective licenses
- Third-party acknowledgments and license list see [`docs/ACKNOWLEDGMENTS.md`](docs/ACKNOWLEDGMENTS.md)
```text
Copyright (c) 2026 ButterFuture
```
---
## Disclaimer
**Read and understand before use. Using this software implies acceptance of the following terms.**
1. **Unofficial** — Not an official Quark / UC / Alibaba product; no official guarantee.
2. **Learning and research** — Do not use for illegal or platform service terms-violating activities.
3. **Use at your own risk** — Consequences on accounts, data, privacy, and membership benefits are borne by the user.
4. **Copyright** — Legality of downloaded and propagated content is your responsibility.
5. **Provided as-is** — No warranty of marketability; interfaces may change, no mandatory maintenance.
6. **Third-party libraries** — Comply with their respective licenses.
Summary see [DISCLAIMER.md](docs/DISCLAIMER.md).
### Rights Notice
Email: `ButterFuture@proton.me`
Subject: `[GoQuark] Rights Notice / Takedown`
Please provide: entity and contact information, specific path/submission, rights basis, desired action.
---
## Security Tips
- Do not leak `config.json` Cookie in chat, screenshots, or CI logs
- Run CLI / MCP in trusted environments only
- Verify binary checksum during installation
---
## Document Directory
| Document | Description |
|------|------|
| [`docs/DISCLAIMER.md`](docs/DISCLAIMER.md) | Disclaimer |
| [`docs/CHANGELOG.md`](docs/CHANGELOG.md) | Changelog |
| [`docs/ACKNOWLEDGMENTS.md`](docs/ACKNOWLEDGMENTS.md) | Third-party dependencies and license statements |
| [`docs/README.md`](docs/README.md) | Document index |
| [`LICENSE`](LICENSE) | AGPL-3.0 full text |
## Status
**v1.0.1** — Login, browse, TUI download center, multi-file download (pause/resume), MCP, self-update, and documentation complete.
Future plans: public repository formal release channel, in-app update checks (optional), richer MCP capabilities.
---
<p align="center">
Made with Go · AGPL-3.0 · Unofficial
</p>
