gaozhangmin/boxplayer/skill

clouddrive-cli

clouddrive-cli turns BoxPlayer cloud-drive accounts into a deterministic command surface for humans and AI agents. It supports Aliyun Drive, OneDrive, Dropbox, Box, 123Pan, 115 Drive, Baidu Netdisk, and PikPak.

This skill is the orientation layer. Discover the live CLI surface first, then choose the smallest safe command path for the user's goal.

The three pillars

• Account and provider discovery — auth list, settings show, and providers capabilities tell you which accounts exist and which operations each provider supports.
• Cloud file operations — files list|walk|tree|stats|info|download|search|mkdir|rename-apply|move-apply|trash-apply provide the stable boundary for reading and changing cloud files.
• Agent workflows — docs read, media *, upload *, organize *, and ops * let agents combine local instructions, cloud inventory, dry-run plans, execution, and rollback.

Install and locate

which clouddrive-cli
clouddrive-cli --help
clouddrive-cli list --format json

If the command is missing, ask the user to install it from BoxPlayer account settings or with npm install -g clouddrive-cli.

There are two install modes:

• BoxPlayer app mode — the Electron app registers clouddrive-cli and exports logged-in account tokens.
• Standalone CLI mode — install with npm and use auth login or auth import-token to add accounts.

Discover first

Do not treat this file as the complete command registry. Start with live discovery:

clouddrive-cli list --format json
clouddrive-cli schema commands
clouddrive-cli auth list --format json
clouddrive-cli settings show --format json
clouddrive-cli providers capabilities --format json

clouddrive-cli list --format json is the source of truth for command metadata such as access, requiresDryRun, destructive, and undoable. providers capabilities is the source of truth for provider-specific support such as search, mkdir, move, rename, trash/delete, upload, recursive walk, path addressing, and file-id addressing.

Universal conventions

Common error codes:

Read workflows

Use bounded reads before large traversals:

clouddrive-cli files stats --provider aliyun --account default --file-id root --depth 2 --format json
clouddrive-cli files stats --provider aliyun --account default --file-id root --output stats.json --format json
clouddrive-cli files tree --provider aliyun --account default --file-id root --depth 1
clouddrive-cli files list --provider aliyun --account default --file-id root --format json
clouddrive-cli files list --provider aliyun --account default --file-id root --limit 100 --format json
clouddrive-cli files list --provider aliyun --account default --file-id root --limit 100 --cursor <nextCursor> --format json
clouddrive-cli files download --provider aliyun --account default --file-id <file-id> --output ./download.bin --format json
clouddrive-cli files search --provider aliyun --account default --name "movie" --limit 50 --format json

Rules of thumb:

• Use stats or shallow tree to understand scale.
• Use search for known keywords.
• Use walk only after narrowing scope or when a full inventory is explicitly needed.
• Avoid raw files tree --json and broad walk on large roots unless you will save and summarize the output locally.

Provider root defaults when --file-id is omitted:

Write workflows

Never apply a write plan first. The safe sequence is:

1. Discover command metadata with clouddrive-cli list --format json.
2. Check provider capability with clouddrive-cli providers capabilities --format json.
3. Generate or read a plan.
4. Run the dry-run or preview command.
5. Show the user a concise summary of planned changes.
6. Execute only after explicit user approval.
7. Record the operation ID and rollback path when available.

Include --rationale on write commands, for example:

clouddrive-cli upload apply upload-plan.json --dry-run --rationale "User asked to back up this folder" --format json

Common write previews:

clouddrive-cli files rename-apply rename-plan.json --current files.json --dry-run --format json
clouddrive-cli files move-apply move-plan.json --dry-run --format json
clouddrive-cli files trash-apply trash-plan.json --format json
clouddrive-cli upload apply upload-plan.json --dry-run --format json
clouddrive-cli organize apply organize-plan.json --dry-run --summary --format json

Notes:

• trash-apply defaults to preview; execution requires --apply.
• Rename and move operations are undoable through ops undo; trash is not.
• Dropbox and Baidu move/trash plans may require path fields in addition to file IDs.
• Upload planning exists for all providers. Real byte upload is wired for providers whose providers capabilities entry has uploadFile: true (aliyun, cloud123, 115, baidu, dropbox, onedrive, box in this build); pikpak remains plan/dry-run only.

Media organization

Recommended flow:

clouddrive-cli docs read ./rules.md --max-chars 50000 --format json
clouddrive-cli docs read ./rules.pdf --pdf-format markdown --pdf-pages 1-3 --format json
clouddrive-cli docs convert ./pdf-folder --output ./out --pdf-format json,html,pdf,markdown,tagged-pdf,text --format json
clouddrive-cli files stats --provider aliyun --account default --file-id <folder-id> --depth 2 --format json
clouddrive-cli files walk --provider aliyun --account default --file-id <folder-id> --output files.json --format json
clouddrive-cli media match --input files.json --format json
# Generate rename-plan.json yourself from rules, inventory, and match output.
clouddrive-cli files rename-apply rename-plan.json --dry-run --format json

media match returns media fields under match, for example { fileId, name, match: { type, title, year, season, episode, confidence, jellyfin_name } }.

For full-drive organization, treat broad plans as risky even if dry-run succeeds. Sample suspicious moves, check whether existing meaningful folders would be flattened into generic Movies or TV Shows, and prefer applying one folder/category at a time.

Rollback

clouddrive-cli ops list --format json
clouddrive-cli ops show <operation-id> --format json
clouddrive-cli ops undo <operation-id> --dry-run --format json
clouddrive-cli ops undo <operation-id> --format json

Always run ops undo --dry-run first. Only rename and move operations have CLI undo.

MCP

clouddrive-mcp exposes the CLI manifest as MCP tools. Tool names and input schemas are generated from the same command manifest used by clouddrive-cli list --format json, so CLI/MCP discovery should stay aligned. Prefer direct CLI commands when:

• You need file output redirection or plan files.
• You are testing CLI behavior during skill/CLI iteration.

Known provider limitations

• OneDrive files search may intermittently fail with Microsoft Graph generalException / HTTP 500. Use files walk plus local filtering as fallback.
• PikPak files search --name may ignore the name query and return root items. Use files walk plus local filtering.
• Baidu files info handles filemetas under either list or info, but errno=12 can still indicate an API/token limitation. Fall back to files walk or files search.
• 115 Open API folder fields may map folders as type: file. Confirm folder-ness by trying files list --file-id <fileId> before planning folder operations.

Don't

• Don't paste this skill's command list into a plan; call clouddrive-cli list --format json.
• Don't run non-dry-run writes without explicit user approval.
• Don't assume root path tokens are portable across providers.
• Don't continue after a structured JSON error without branching on error.code.
• Don't emit huge raw inventories to the user; save, summarize, and sample.