Box Developer Documentation

Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

Using Options and Bulk Commands

Using Options and Bulk Commands

Options

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

You can use a CSV file to execute commands in bulk. Each row of the spreadsheet is treated as an individual API call.

To execute a bulk command, use the option --bulk-file-path=<PATH_TO_CSV>, where <PATH_TO_CSV> is 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

Drag the CSV file from your finder window/file explorer to the terminal/command line window to auto-populate the path.

To specify the column names for your CSV file, go to 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. You can also use 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 file. 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 file. 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

For more details on bulk commands read this document.

Summary

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