Box

Box CLI skill for working with files, folders, metadata, search, and Box AI in headless environments.

Install

openclaw skills install @hbkwong/box-cli

box

Use the official box CLI to interact with the Box API from OpenClaw.

This skill is designed for headless deployments (e.g. Railway, CI, servers). It does not use OAuth login flows or short-lived developer tokens.

Instead, it expects Bring Your Own Credentials using:

Client Credentials Grant (CCG) --- recommended
JWT Server Auth --- optional

🔐 Authentication (Bring Your Own Credentials)

This skill does not manage authentication automatically.

You must provide credentials before using Box commands.

⚠️ Never commit credential files (CCG JSON or JWT JSON) to git.

Add the following to your .gitignore:

text

box-ccg.json
box-jwt.json
.secrets/

🔑 User-Provided JSON Configuration (Required)

Users must supply their own Box CCG configuration file.
The skill does not generate credentials or manage secrets.

Your file should look like:

json

{
  "boxAppSettings": {
    "clientID": "client_id_here",
    "clientSecret": "client_secret_here"
  },
  "enterpriseID": "enterprise_id_here"
}

This file can be named box-ccg.json and placed in your deployment environment before registering it with Box CLI.

Option A --- Provide a CCG Config File (Recommended)

Create a Box Custom App using:

Server Authentication (Client Credentials Grant)

You will need:

clientID
clientSecret
enterpriseID

Create your config file in a secure location outside the workspace, e.g.:

/data/.secrets/box-ccg.json

⚠️ Avoid storing credentials inside the workspace directory — it may be tracked by git or accessible to other tools.

With:

{ "boxAppSettings": { "clientID": "YOUR_CLIENT_ID", "clientSecret": "YOUR_CLIENT_SECRET" }, "enterpriseID": "YOUR_ENTERPRISE_ID" }

Secure it:

chmod 600 /data/.secrets/box-ccg.json

box configure:environments:add /data/.secrets/box-ccg.json --ccg-auth --name ccg --set-as-current box configure:environments:set-current ccg

Optional: Run as a managed user instead of the service account:

box configure:environments:add /data/.secrets/box-ccg.json --ccg-auth --ccg-user "USER_ID" --name ccg-user --set-as-current

Option B --- Use Environment Variables (.env supported)

Set:

BOX_CLIENT_ID BOX_CLIENT_SECRET BOX_ENTERPRISE_ID

Generate config:

mkdir -p /data/.secrets

cat < /data/.secrets/box-ccg.json { "boxAppSettings": { "clientID": "$BOX_CLIENT_ID", "clientSecret": "$BOX_CLIENT_SECRET" }, "enterpriseID": "$BOX_ENTERPRISE_ID" } EOF

chmod 600 /data/.secrets/box-ccg.json

Then register:

box configure:environments:add /data/.secrets/box-ccg.json --ccg-auth --name ccg --set-as-current

Option C --- JWT Server Auth (Alternative)

If using JWT:

box configure:environments:add /data/.secrets/box-jwt.json --name jwt --set-as-current

✅ Verify Authentication

box configure:environments:get --current box users:get me

Note: With CCG, you are authenticated as either: - The service account, or - A managed user (if --ccg-user is used)

Access depends on that identity's permissions.

📂 Common Operations

Browse Folders

box folders:get 0 box folders:list-items 0 --json

Upload

box files:upload ./report.pdf --parent-id 0

Download

box files:download 123456789 --destination ./downloads --create-path

Search

box search "quarterly plan" --type file

Metadata

box files:metadata:get-all 123456789 box files:metadata:add 123456789 --template-key employeeRecord --data "department=Sales"

🤖 Box AI Usage (No Local LLM Downloads)

This skill supports using Box AI directly via the Box platform.

AI operations run within Box, respecting: - File permissions - Enterprise security - Data governance - Audit controls

No file download + local LLM inference required.

Ask Questions About a File

box ai:ask --item-id 123456789 --item-type file --prompt "Summarize this document and identify risks."

Extract Structured Data

box ai:extract-structured --item-id 123456789 --item-type file --schema '{"fields":[{"name":"invoice_number","type":"string"},{"name":"total","type":"number"}]}'

Extract Text

box ai:extract --item-id 123456789 --item-type file

🧠 Tips for Agents & Automation

Use JSON output when parsing results:

box folders:list-items 0 --json

Prefer CCG for headless deployments because:

No browser required
No expiring developer tokens
Suitable for automation
Works cleanly in Railway

🔒 Security Notes

Do not commit credential files.
Restrict file permissions (chmod 600).
Use least-privilege app scopes.
Avoid granting broad enterprise-wide access to service accounts.
Prefer a dedicated demo folder when showcasing functionality.

🚀 Deployment Notes (Railway / CI)

Ensure /data/workspace is writable (for file operations).
Ensure /data/.secrets exists and is writable (for credential storage).
Box CLI stores environments in ~/.box.
If containers are ephemeral, re-run configure step on deploy.
Use Railway Variables instead of pasting secrets into chat.

This skill exposes the full surface area of the Box CLI.

Explore commands:

box --help box folders --help box files --help box ai --help

Box