zpan/docs/roadmap/v2.9.md

v2.9 — Agent CLI

Ship ZPan's command-line tool as an automation client for agents, scripts, and CI/CD. This CLI is not the foundation for desktop sync. It is a separate client surface optimized for reliable command execution and machine-readable output.

Product Boundary

• Community gets the core CLI for personal and self-hosted automation.
• Pro / Business may raise API limits or expose operator-only commands when the underlying feature is paid-tier gated.
• Desktop sync clients do not call this CLI as their internal engine. They use sync-specific APIs and OS integrations in their own client projects.

Why CLI Here

Agents and automation need stable verbs:

• upload a file
• list folders
• create a folder
• move / copy / delete objects
• create a share link
• download an object
• inspect quota and task state

These map naturally to shell commands with JSON output. They do not require a filesystem-provider integration, long-running sync daemon, or platform-specific desktop packaging.

Major Features

Command Surface

Initial command groups:

zpan auth login
zpan auth status
zpan auth logout

zpan file ls
zpan file upload
zpan file download
zpan file mkdir
zpan file mv
zpan file cp
zpan file rm
zpan file stat

zpan share create
zpan share list
zpan share revoke

zpan space list
zpan space use
zpan quota get
zpan task list
zpan task watch

Command names should be predictable and script-friendly. Prefer explicit flags over interactive prompts, with optional prompts only for humans running the tool manually.

Agent-Friendly Output

The CLI must be easy for coding agents and MCP-style tools to call.

• --json for every command that returns data
• Stable exit codes
• Errors printed as structured JSON when --json is active
• No progress bars in non-TTY mode
• --quiet and --no-color
• Idempotency keys for commands that create or mutate resources where useful
• Clear stderr/stdout separation

Authentication

Supported auth paths:

• Personal API key for simple automation
• Device authorization flow for human bootstrap
• Environment variable token for CI/agent runtime use
• Config profiles for multiple ZPan instances

The CLI should never ask users to paste browser cookies.

Upload And File Management

The CLI should use the same object upload flow as the browser:

1. Ask ZPan to create an upload draft and presigned instructions.
2. Upload bytes directly to object storage.
3. Complete the upload through ZPan.

It should support:

• single-file upload
• recursive directory upload as an explicit command mode
• conflict strategies: fail, keep both, replace
• target space and folder selection
• resumable multipart upload where the server already supports it

This is file management automation, not backup/sync semantics. Local deletions must not imply remote deletions unless the user runs an explicit delete command.

Packaging

The implementation language should be chosen during task planning. The product contract is more important than the runtime.

Packaging requirements:

• macOS, Linux, Windows
• installable in CI
• easy for agents to locate and execute
• versioned independently enough that agent tooling can pin a known CLI version

If implemented in this repository, keep the CLI isolated from the web frontend and server runtime so it does not complicate normal ZPan deployment.

OpenAPI Contract

The CLI should use the public REST/OpenAPI surface, not private frontend helpers. If an existing route is awkward for CLI use, improve the API contract rather than special-casing the CLI.

Frontend code continues to use Hono RPC wrappers.

Non-goals for v2.9

• Desktop sync engine
• Apple File Provider, Windows Cloud Files, Linux filesystem integration
• Flutter, Tauri, Swift, Kotlin, or other graphical clients
• Bidirectional sync or conflict replication
• Enterprise / legacy identity protocols such as LDAP, SCIM, or SAML
• Folder-level ACLs or custom roles

User Scenarios

Coding agent:

The agent uploads a generated artifact, creates a share link, and posts the link back to the user without needing browser automation.

CI release workflow:

A GitHub Actions job uploads build artifacts to ZPan and creates a stable share link for release notes.

Power user:

I run zpan file upload ./dist --target /releases/v2.9 --recursive --json and get a machine-readable summary of uploaded files and share URLs.

Future Work

• MCP server wrapping the CLI or using the same OpenAPI client
• Admin/operator command groups for Business features
• Bulk migration helpers
• Shell completions and package-manager distribution polish