Box Cloud Filesystem

Overview

Operate Box through numeric file and folder IDs, narrow sharing defaults, and verified receipts. The plugin's Write/Edit hook only queues local workspace changes for review and never uploads automatically; see the reviewed sync pattern for the complete flow.

Prerequisites

box version
box users:get me --json

• Install the current supported Box CLI 4.x through an operator-approved Node package workflow; do not install packages automatically.
• Use box login for interactive OAuth. JWT and CCG require a Box Platform App, appropriate scopes, secure configuration, and enterprise admin authorization.
• Never request or pass access tokens through chat or the CLI --token flag.
• The bundled workspace scripts require Bash and jq.

Workflow

1. Classify the request as discover, read, create, update, expose, synchronize, or destructive.
2. Verify the active Box identity with box users:get me --json and report the account or enterprise without exposing credentials.
3. Discover the target by listing or searching. Use Read, Glob, and Grep only for the local files the user placed in scope.
4. Resolve every remote target to a numeric Box ID. Names are not unique.
5. Preview the operation:

• uploads: local path, size, parent folder ID, and collision result;
• updates: file ID, local path, and remote content_modified_at;
• sharing: target ID, access level, download/edit flags, and expiry;
• deletion or bulk moves: every target and recoverability.

1. Execute only the operation the user authorized. Ask before public/open links, deletes, bulk reorganizations, overwriting remote changes, or widening app access. Use Write or Edit only for requested local artifacts.
2. Re-read the affected Box item and return the receipt contract below.

Trust zones

Never use --yes to suppress a Box CLI confirmation for expose or destructive operations.

Current command surface

box folders:items FOLDER_ID --json --fields name,id,type,content_modified_at
box search "query" --type file --json
box files:get FILE_ID --json --fields name,size,content_modified_at,shared_link
box files:download FILE_ID --destination LOCAL_PATH
box files:upload LOCAL_PATH --parent-id FOLDER_ID --json
box files:versions:upload FILE_ID LOCAL_PATH --json
box files:share FILE_ID --access collaborators --json

Use box COMMAND --help as command truth. The operations guide covers moves, folders, sharing, and recovery.

Reviewed workspace queue

Initialize only when the user explicitly selects a Box folder and local path:

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

Initialization performs a Box read, downloads the folder, and stores a permission-restricted local config. Subsequent Write/Edit hooks add eligible relative paths to .box-sync-pending; hidden files and credential-like names are excluded. The Stop hook reports the queue and performs no upload.

Before syncing, list each remote item again, compare modification timestamps, show create/update/conflict groups, and obtain approval. Upload changed known files with files:versions:upload; upload genuinely new files with files:upload. Never infer a remote deletion from a missing local file.

Output

Return:

• Box account context and target folder ID;
• operation and local/remote target;
• created or updated file/folder ID;
• sharing access, expiry, and URL when applicable;
• preflight comparison and any conflict;
• command exit result plus post-operation metadata;
• queued/skipped paths and the reason.

Error Handling

• 401/expired auth: run box login; never ask for a token in chat.
• 403: report the missing scope or collaboration/admin boundary; do not widen access automatically.
• 404: verify identity and ID by re-listing the parent.
• 409/name collision: choose a version upload or an explicitly distinct name.
• 429: honor retry guidance and reduce/batch read operations; do not loop indefinitely.
• Remote changed since download: stop and ask whether to keep remote, local, or both.
• Partial bulk failure: re-list the target, report confirmed successes, and retry only unresolved items after approval.
• Hook queue failure: preserve local work; report that no Box upload occurred.

Examples

Update an existing file without creating a duplicate:

box files:get FILE_ID --json --fields name,content_modified_at
box files:versions:upload FILE_ID approved-report.md --json
box files:get FILE_ID --json --fields name,version_number,content_modified_at

Create a collaborators-only link after confirming the audience:

box files:share FILE_ID --access collaborators --json

Resources

• Box CLI operations and recovery
• Reviewed workspace synchronization
• Box CLI source and generated command docs
• Box security model