Join the first BoxWorks Hackathon for Good - customers, partners, and the developer community are welcome to participate in the 48 hour Hack to benefit The Nature Conservancy.

Learn more and register!

Using Options and Bulk Commands

Using Options and Bulk Commands


Options provide additional, optional functionality to use with a CLI command. You may also hear these referred to as flags or arguments. As mentioned in the previous step, --help is an example of an option.

To see all valid options for a command, visit the GitHub repository.

For example, look at the command documentation for deleting folders. You will see a list of options to use with this command, such as --recursive or --force.

As-User Header

To use the as-user header, add the --as-user=USERID option to the end of the command.

For example, the following command will create a folder called Example_Folder at the root level in user ID 123456’s account.

box folders:create 0 Example_Folder --as-user=123456

Only Service Accounts and Admins are able to use the as-user header. If your application was not authorized with the necessary scopes or you configured your CLI to obtain a default token for another user, this call may fail. Add -v or --verbose to your command for verbose error logging.

Bulk Commands

A csv file can be used to execute commands in bulk and each row of the spreadsheet is treated as an individual API call.

To execute a bulk command, use the option --bulk-file-path=pathtoacsv, where pathtoacsv is replaced with the local path of a csv file containing the necessary information.

As an example, let's create folders using the command box folders:create --bulk-file-path=pathtoacsv

You can drag the csv file from your finder window/file explorer to the terminal/command line window to auto-populate the path.

To determine column names for your csv, visit the GitHub repository documentation and look at the argument names or use the --help option. In this case, these are PARENTID and NAME and are case insensitive. Here is a csv template for this example bulk create folders command.

Executing the command below creates three folders at the root level, 0, of the Service Account's folder tree.

box folders:create --bulk-file-path=/Users/ExampleUser/Desktop/bulkcreatefolders.csv

Bulk Commands with Options

Passing an option in a command will automatically apply to it to each row in the csv. For example, box folders:collaborations:create --bulk-file-path=pathtocsv --role=editor will create collaborations for each user in the csv as an editor.

However, you can also use options in the csv. Building on the last example, instead of using the --role=editor option in the command itself, it can be a column called role. The command itself becomes:

box folders:collaborations:create --bulk-file-path=pathtocsv


  • You used an option with a command and/or a bulk command.