box-cli

name	box-cli
description	Use this skill for all Box operations — uploading, downloading, searching, and managing files and folders in Box. Uses the Box CLI (@box/cli) via Bash commands with a developer token.

Box CLI

Use the Box CLI (@box/cli) for all Box operations. Run commands via Bash with npx @box/cli.

Authentication: Always pass the developer token inline with --token $BOX_DEVELOPER_TOKEN. No persistent configuration is needed.

Output format: Always pass --json to get structured JSON output (except for download commands).

Use --help to see all commands to know what to use.

Box File Output Format (CRITICAL)

Every time you mention a Box file in your response, you MUST place a JSON code fence immediately after the sentence that introduces it. Each file gets its own separate code fence. NEVER group all files into a single JSON array. NEVER list files as bullet points or plain text without a JSON code fence for each one.

The format for each file reference is a fenced JSON array with one object:

```json
[{ "fileId": "ID", "fileName": "NAME", "type": "TYPE", "boxPath": "PATH", "sharedLink": "URL" }]
```

Required: fileId, fileName. Optional: type, boxPath, sharedLink.

Include sharedLink whenever you create a shared link for a file (e.g. after uploading to root). Use the shared_link.url value from the files:shared-links:create response. The UI needs this to preview files owned by the service account.

WRONG (do not do this):

• Listing files as bullet points or text, then putting one big JSON array at the end
• Describing all files first, then outputting JSON
• Grouping more than 2-3 files in a single JSON array

RIGHT pattern — alternate between a short description and its file block:

Found a W-2 from Acme Robotics:

```json
[{ "fileId": "111", "fileName": "W2_Acme.pdf", "type": "W-2", "boxPath": "Tax Docs/02_Income" }]
```

Here is the uploaded spreadsheet:

```json
[{ "fileId": "222", "fileName": "auto_loan.xlsx", "sharedLink": "https://app.box.com/s/abc123" }]
```

The UI converts each JSON code fence into a clickable file card inline in the chat. If you put all files in one block, they all appear bunched together at the bottom instead of next to their descriptions.

Public Shared Links for Root Folder Uploads

When uploading a file to the root folder (folder ID 0), you MUST always create an open shared link immediately after uploading:

npx @box/cli files:shared-links:create FILE_ID --access open --token $BOX_DEVELOPER_TOKEN --json

This ensures all files at the root level are publicly accessible. Do this automatically — do not wait for the user to ask.

Search Syntax

The search command takes a single positional QUERY argument. The entire search term must be one quoted string. There is no OR operator — if you need to search for multiple terms, run separate search commands for each.

# CORRECT — single quoted query
npx @box/cli search "receipt" --token $BOX_DEVELOPER_TOKEN --json
npx @box/cli search "W-2" --type file --token $BOX_DEVELOPER_TOKEN --json

# WRONG — multiple unquoted words become separate arguments and fail
npx @box/cli search receipt OR invoice --token $BOX_DEVELOPER_TOKEN --json

Useful search flags: --type file|folder|web_link, --file-extensions png,pdf, --ancestor-folder-ids FOLDER_ID, --limit N.

Tips

• After uploading a file, use files:get to retrieve the shared link or create one with files:shared-links:create.
• The search command may take a few seconds for newly uploaded files to become indexed.
• Use --json on all commands (except downloads) to get parseable output.
• If a command fails with a 503, retry after a short delay — Box occasionally returns transient errors.