Bulk operations

Use this workflow for more than a handful of files. Choose the current OAuth actor before inventorying; it can only process content that identity can access.

Workflow

Inventory → classify if needed → plan → confirm → execute → verify → report

Inventory and plan

bash

box folders:items <FOLDER_ID> --json --max-items 1000 --fields id,name,type,parent

Paginate until every item is accounted for. Record IDs, names, types, target folder IDs, and a completed-ID log. Before broad moves, access changes, or AI use, present the scope and ambiguous cases for approval.

Classify content

Prefer deterministic filename, extension, and existing-metadata rules. For semantic classification, use Box AI rather than downloading file bodies:

bash

box ai:ask --items=id=<FILE_ID>,type=file \
  --prompt "Classify as invoice, receipt, contract, report, or other." --json

For known fields, use ai:extract-structured; for variable fields, use ai:extract. Sample a small representative set before processing a large batch. Disclose Box AI unit use and obtain confirmation before a material AI batch.

Execute and recover

bash

box folders:create <PARENT_ID> "Category" --json --fields id,name
box files:move <FILE_ID> <TARGET_FOLDER_ID> --json --fields id,name,parent

Process ordered CLI mutations serially and log each success or failure. On 409, find and reuse the existing target. On 429, honor Retry-After and retry the same request. Resume from inventory minus completed IDs; do not restart blindly.

Use a documented --bulk-file-path workflow when the relevant command supports it. Use bounded SDK concurrency only when the application owns retries, idempotency, and rate-limit handling.

Verify and report

List each destination and the source folder, then compare IDs and counts with the plan. Report links to the source folder, destination folders, and exceptions. Do not dump hundreds of item links unless the user asks for a manifest.