thedixitjain 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
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:
- Classify the intent — discover, read, upload, update, organize, sync, share, or cleanup
- Orient — run
box users:get --me, identify target folder ID, check the trust zone - Discover — list or search Box to understand what exists before modifying anything
- Execute — perform the operation (see
references/operations-guide.mdfor commands) - 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
- Inspect folder contents before writing to it.
- Use file IDs, not filenames, when updating — names are not unique in Box.
- Prefer
box files:versions:upload FILE_IDfor updates. Avoids 409 conflicts, preserves history. - Never delete unless explicitly requested. No "convenience cleanup."
- Never create
--access openshared links unless user says "public" or "open." - Summarize bulk operations before executing.
- Report file ID, folder ID, and action type after every write.
- 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)
Source: jeremylongshore/claude-code-plugins-plus-skills → plugins/productivity/box-cloud-filesystem/skills/box-cloud-filesystem/SKILL.md