box-cloud-filesystem

name	box-cloud-filesystem
description	Cloud filesystem operations via Box CLI. Use when the user mentions Box, cloud files, cloud storage, uploading to the cloud, sharing files, document management, or syncing project files offsite. Trigger with "upload to box", "save to cloud", "pull from box", "search my box files", "share this file", "box sync", "cloud backup", or "box filesystem".
allowed-tools	Read, Write, Edit, Bash(box:*), Bash(npm:*), Bash(npx:*), Glob, Grep
version	1.0.0
author	Jeremy Longshore <[e-mail]>
license	MIT
compatible-with	claude-code, codex, openclaw
tags	["box","cloud-storage","filesystem","sync","collaboration","document-management"]

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)