box-cloud-filesystem

Box Cloud Filesystem

Two modes, one goal: treat Box like a local filesystem.

Transparent mode — initialize a workspace, then every Write or Edit inside it auto-syncs to Box via PostToolUse hooks. No box commands needed.

Explicit mode — search, download, share, or organize files using Box CLI commands directly. See references/operations-guide.md for the full command reference.

Contents

• Overview
• Prerequisites
• Instructions
• Workspace Sync Pattern
• Output
• Error Handling
• Examples
• Resources

Overview

Box CLI (@box/cli) wraps the full Box API as shell commands. This skill adds three layers:

• Hooks (transparent sync) — PostToolUse hooks on Write/Edit auto-upload changed files to Box.
• Operational judgment — file identity via numeric IDs, version uploads over duplicates, narrow sharing defaults, manifest-based conflict detection.
• Sync patterns — pull/work/push workflow with automatic hook-driven uploads and conflict resolution.

Key principle: inspect before acting, report after acting. Folder ID 0 is always root.

Prerequisites

npm install --global @box/cli
box login
box users:get --me   # verify auth + enterprise context

Auth methods: OAuth (interactive), JWT (automation), CCG (server-to-server), Developer Token (testing, 60 min).

jq is required for the hook scripts.

Instructions

Follow this workflow for every Box operation:

1. Classify the intent — discover, read, upload, update, organize, sync, share, or cleanup
2. Orient — run box users:get --me, identify target folder ID, check the trust zone
3. Discover — list or search Box to understand what exists before modifying anything
4. Execute — perform the operation (see references/operations-guide.md for commands)
5. Report — return file IDs, folder IDs, action types, and any conflicts

Operation Trust Zones

Zone	Operations	Behavior
Read	search, list, download, metadata	Execute freely
Create	upload new, create folders	Verify parent folder ID first
Update	version upload, move, copy	Use file ID, prefer files:versions:upload
Expose	share links, access levels	Default collaborators, never open unless explicit
Destructive	delete, bulk reorganize	Only on explicit request; summarize first

Safety Rules

1. Inspect folder contents before writing to it.
2. Use file IDs, not filenames, when updating — names are not unique in Box.
3. Prefer box files:versions:upload FILE_ID for updates. Avoids 409 conflicts, preserves history.
4. Never delete unless explicitly requested. No "convenience cleanup."
5. Never create --access open shared links unless user says "public" or "open."
6. Summarize bulk operations before executing.
7. Report file ID, folder ID, and action type after every write.
8. If unexpected files exist in a folder, stop and ask before modifying.

Quick Command Reference

box folders:items FOLDER_ID --json                    # list folder
box search "query" --type file --json                  # search
box files:download FILE_ID --destination ./             # download
box files:upload ./file.txt --parent-id FOLDER_ID       # upload new
box files:versions:upload FILE_ID ./file.txt            # update existing
box files:share FILE_ID --access collaborators          # share (narrow)
box folders:download FOLDER_ID --destination ./         # bulk download

Full command reference with examples: references/operations-guide.md

Workspace Sync Pattern

Initialize a workspace, work locally, push changes back. The manifest tracks file IDs.

${CLAUDE_PLUGIN_ROOT}/scripts/box-init-workspace.sh FOLDER_ID /tmp/box-workspace

With hooks active, every Write/Edit auto-syncs. For manual sync, compare local state against the manifest:

• Changed file in manifest → box files:versions:upload FILE_ID (version update)
• New file not in manifest → box files:upload --parent-id FOLDER_ID (new upload)
• Deleted locally → do NOT auto-delete from Box; ask user
• Conflict detected → warn user before overwriting

Full sync workflow with conflict detection: references/sync-pattern.md

Output

Every write operation returns:

• File/folder ID
• Parent folder ID
• Action type (created / versioned / moved / copied / shared)
• Access level (if sharing)
• Conflicts or skipped items

Read operations return JSON with id, name, size, modified date.

Error Handling

Error	Recovery
Not Found (404)	Verify ID with box search or re-list parent folder
Conflict (409)	Use files:versions:upload to update, or --name for distinct file
Forbidden (403)	Re-run box login or check JWT scopes
Rate Limited (429)	CLI retries automatically; batch via --bulk-file-path
Auth expired	Run box login; use JWT/CCG for production
box: command not found	npm install --global @box/cli
Name collision	Use file ID, never filename, to identify targets
Local/remote divergence	Re-download, diff, ask user which to keep

Always report what failed and what succeeded. Never silently skip. Full error table: references/operations-guide.md

Examples

Back up docs to Box:

box folders:create 0 "my-project-docs" --json
box files:upload docs/README.md --parent-id FOLDER_ID
box folders:share FOLDER_ID --access collaborators

Pull, analyze, push back:

box search "Q1 sales" --type file --json
box files:download FILE_ID --destination /tmp/box-workspace/
# analyze locally, then push result
box files:upload /tmp/box-workspace/summary.md --parent-id PARENT_ID

Workspace sync (with hooks):

${CLAUDE_PLUGIN_ROOT}/scripts/box-init-workspace.sh FOLDER_ID /tmp/box-workspace
# edit files normally — hooks auto-sync to Box

More detailed examples: references/sync-pattern.md

Resources

• Box CLI: https://github.com/box/boxcli
• Box Developer Docs: https://developer.box.com/
• Box API Reference: https://developer.box.com/reference/
• Box pricing: https://www.box.com/ (free tier available for individual users)