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