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.
- Getting Started
- Usage
- Command Topics
- Questions, Bugs, and Feature Requests?
- Versions
- Contributing to the Box CLI
- Copyright and License
The most convenient way to get start with Box CLI is to follow Box CLI with OAuth 2.0 guide. You will be guided how to configure Box application and install CLI on your machine.
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.
To install the latest CLI on your machine, download the latest .exe
for Windows or .pkg
for macOS for the latest release.
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
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 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"
$ 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'
-
aj_cli_test autocomplete
- Display autocomplete installation instructions -
aj_cli_test collaboration-allowlist
- List collaboration allowlist entries -
aj_cli_test collaborations
- Manage collaborations -
aj_cli_test collections
- List your collections -
aj_cli_test comments
- Manage comments on files -
aj_cli_test configure
- Configure the Box CLI -
aj_cli_test device-pins
- List all the device pins for your enterprise -
aj_cli_test events
- Get events -
aj_cli_test file-requests
- Copies existing file request to new folder -
aj_cli_test files
- Manage files -
aj_cli_test folders
- Manage folders -
aj_cli_test groups
- List all groups -
aj_cli_test help
- Display help for the Box CLI -
aj_cli_test legal-hold-policies
- List legal hold policies -
aj_cli_test login
- Sign in with OAuth and set a new environment -
aj_cli_test metadata-cascade-policies
- List the metadata cascade policies on a folder -
aj_cli_test metadata-query
- Create a search using SQL-like syntax to return items that match specific metadata -
aj_cli_test metadata-templates
- Get all metadata templates in your Enterprise -
aj_cli_test oss
- Print a list of open-source licensed packages used in the Box CLI -
aj_cli_test recent-items
- List information about files accessed in the past 90 days up to a 1000 items -
aj_cli_test request
- Manually specify a Box API request -
aj_cli_test retention-policies
- List all retention policies for your enterprise -
aj_cli_test search
- Search for files and folders in your Enterprise -
aj_cli_test shared-links
- Manage shared links -
aj_cli_test sign-requests
- List sign requests -
aj_cli_test storage-policies
- List storage policies -
aj_cli_test tasks
- Manage tasks -
aj_cli_test terms-of-service
- List terms of services for your enterprise -
aj_cli_test tokens
- Get a token. Returns the service account token by default -
aj_cli_test trash
- List all items in trash -
aj_cli_test users
- List all Box users -
aj_cli_test watermarking
- Apply a watermark on an item -
aj_cli_test web-links
- Manage web links -
aj_cli_test webhooks
- List all webhooks
Browse the issues tickets! Or, if that doesn't work, file a new one and someone will get back to you. If you have general questions about the Box API, you can post to the Box Developer Forum.
We use a modified version of Semantic Versioning for all changes. See version strategy for details which is effective from 30 July 2022.
Only the current MAJOR version of SDK is supported. New features, functionality, bug fixes, and security updates will only be added to the current MAJOR version.
A current release is on the leading edge of our SDK development, and is intended for customers who are in active development and want the latest and greatest features. Instead of stating a release date for a new feature, we set a fixed minor or patch release cadence of maximum 2-3 months (while we may release more often). At the same time, there is no schedule for major or breaking release. Instead, we will communicate one quarter in advance the upcoming breaking change to allow customers to plan for the upgrade. We always recommend that all users run the latest available minor release for whatever major version is in use. We highly recommend upgrading to the latest SDK major release at the earliest convenient time and before the EOL date.
Version | Supported Environments | State | First Release | EOL/Terminated |
---|---|---|---|---|
3 | Node.js >= 12 and <= 14 | Supported | 01 Feb 2022 | TBD |
2 | EOL | 14 Dec 2018 | 01 Feb 2022 | |
1 | EOL | 01 Nov 2017 | 14 Dec 2018 |
- Clone this repo.
- Run
npm install
. - Run
npm test
to ensure everything is working. - Make the changes you want in the
src/
directory. Be sure to add corresponding tests in thetest/
directory! - Create a pull request with your changes — we'll review it and help you get it merged.
For more information, please see the Contribution guidelines.
Copyright 2018 Box, Inc. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
This software includes third party libraries, which are distributed under their own licenses' terms; see LICENSE-THIRD-PARTY.txt for details.