<p align="center"> <img src="https://github.com/box/sdks/blob/master/images/box-dev-logo.png" alt= “box-dev-logo” width="30%" height="50%"> </p>

Box CLI

The Box CLI is a user-friendly command line tool which allows both technical and non-technical users to leverage the Box API to perform routine or bulk actions. There is no need to write any code, as these actions are executed through a set of commands.

Among other features, Box CLI includes the following functionality:

• Bulk actions - A csv file can be used to execute commands in bulk, and each row of the spreadsheet is treated as an individual API call.
• As-User header - Act on behalf of another user.
• Search API - Search for files and folders in your Box Enterprise account.

Table of contents

<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

• Getting Started
  • CLI Installation
    • Windows & macOS Installers
    • Linux & Node install
  • Quick Login with the Official Box CLI App
  • CLI and Server Authentication with JWT
  • Logout
• Secure Storage
  • What is Stored Securely
  • Platform Support
  • Linux Installation
  • Automatic Migration
  • Data Location
• Usage
• Command Topics
  • Questions, Bugs, and Feature Requests?
  • Versions
    • Supported Version
    • Version schedule
  • Contributing to the Box CLI
  • Copyright and License

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Getting Started

CLI Installation

Installers are available for Windows and macOS. However, the raw source-code is available if you would like to build the CLI in other environments.

Windows & macOS Installers

To install the latest CLI on your machine, download the latest .exe for Windows or .pkg for macOS for the latest release.

Linux & Node install

Additionally, the CLI can be installed as a Node package on any platform, including Linux. For this to work, you will need to have Node JS installed on your machine.

npm install --global @box/cli

Quick Login with the Official Box CLI App

After installation, run box login to sign in. You will be prompted with three options:

• [1] Official Box CLI App — No app setup required. Uses predefined scopes limited to content actions.
• [2] Your own Platform OAuth app — Enter your Client ID and Client Secret for custom scopes or specific configuration.
• [q] Quit — Exit the login flow.

You can also paste a Client ID directly at the prompt (any input between 16 and 99 characters is recognized as a Client ID).

Quick start — skip the prompt and go directly to authorization with the Official Box CLI App:

box login -d

A browser window opens for authorization. Once you grant access, the CLI creates a new environment and you're ready to go. See the authentication docs for more details.

Platform App — run box login, choose [2], and enter your credentials from the Box Developer Console. See the Box CLI with OAuth 2.0 guide and the authentication docs for setup instructions.

CLI and Server Authentication with JWT

Alternatively, to get started with the Box CLI, download and install CLI, set up a Box application using Server Authentication with JWT and download the JSON configuration file from the Configuration page of your Platform App in the Box Developer Console following JWT CLI Guide. Then, set up the CLI by pointing it to your configuration file:

$ box configure:environments:add PATH_TO_CONFIG_FILE
Successfully added CLI environment "default"

If you manually generated your own private key to use with JWT authentication, you will need to point the CLI to the location of your private key file:

$ box configure:environments:add PATH_TO_CONFIG_FILE --private-key-path PATH_TO_PRIVATE_KEY --name ManualKey
Successfully added CLI environment "ManualKey"

Logout

To sign out from the current environment, run:

box logout

This revokes the access token on Box and clears the local token cache. For OAuth, run box login to authorize again. For CCG and JWT, a new token is fetched automatically on the next command. Use -f to skip the confirmation prompt, or --on-revoke-failure=clear / --on-revoke-failure=abort to control behavior when token revocation fails. See box logout for full details.

Secure Storage

The Box CLI uses secure storage to protect your sensitive data:

What is Stored Securely

• Environment Configuration: Client IDs, client secrets, and enterprise IDs, private keys and public keys
• Authentication Tokens: Access tokens and refresh tokens for all configured environments

Platform Support

| Platform | Secure Storage | Installation Required | |----------|---------------|----------------------| | macOS | Keychain | Built-in | | Windows | Credential Manager | Built-in | | Linux | Secret Service (libsecret) | May require installation |

Linux Installation

On Linux systems, you need to install libsecret-1-dev for secure storage.

Note: If libsecret is not installed, the CLI will automatically fall back to storing credentials in plain text files in ~/.box/. You can still use the CLI, but for security, we recommend installing libsecret.

Automatic Migration

When you upgrade to a version with secure storage support:

• Existing plaintext credentials are automatically read
• On the next token refresh or configuration update, credentials are migrated to secure storage
• Old plaintext files are automatically deleted after successful migration
• No manual action required!

Data Location

• Secure Storage: Credentials stored in your OS keychain/credential manager
• Fallback (if secure storage unavailable): ~/.box/box_environments.json and ~/.box/{environment}_token_cache.json

Usage

$ box --version
box-cli/0.0.0 darwin-x64 node-v10.10.0
$ box users:get --help
Get information about a Box user

USAGE
  $ box users:get [ID]

ARGUMENTS
  ID  [default: me] ID of the user to get; defaults to the current user

OPTIONS
  -h, --help                             Show CLI help
  -s, --save                             Save report to default reports folder on disk
  -t, --token=token                      Provide a token to perform this call
  -v, --verbose                          Show verbose output, which can be helpful for debugging
  -y, --yes                              Automatically respond yes to all confirmation prompts
  --as-user=as-user                      Provide an ID for a user
  --bulk-file-path=bulk-file-path        File path to bulk .csv or .json objects
  --csv                                  Output formatted CSV
  --fields=fields                        Comma separated list of fields to show
  --json                                 Output formatted JSON
  --no-color                             Turn off colors for logging
  --save-to-file-path=save-to-file-path  Override default file path to save report
$ box users:get
Type: user
ID: '77777'
Name: Example User
Login: user@example.com
Created At: '2016-12-07T17:30:40-08:00'
Modified At: '2018-11-15T17:33:06-08:00'
Language: en
Timezone: America/Los_Angeles
Space Amount: 10737418240
Space Used: 53569393
Max Upload Size: 5368709120
Status: active
Job Title: ''
Phone: ''
Address: ''
Avatar URL: 'https://app.box.com/api/avatar/large/77777'

<!-- commands -->

Command Topics

• box ai - Sends a request to supported LLMs using Box AI. This is intended for direct use, not by AI agents.
• box autocomplete - Display autocomplete installation instructions
• box collaboration-allowlist - List collaboration allowlist entries
• box collaborations - Manage collaborations
• box collections - List your collections
• box comments - Manage comments on files
• box configure - Configure the Box CLI
• box device-pins - List all the device pins for your enterprise
• box events - Get events
• box file-requests - Copies existing file request to new folder
• box files - Manage files
• box folders - Manage folders
• box groups - List all groups
• box help - Display help for the Box CLI
• box integration-mappings - List Slack integration mappings
• box legal-hold-policies - List legal ho