Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.box.com/llms.txt

Use this file to discover all available pages before exploring further.

Authenticate the Box CLI on machines without a browser using manual code entry. Use the --code flag to authenticate the Box CLI in headless environments such as remote servers, containers, or CI/CD pipelines where no browser is available.

​
Prerequisites

  • The Box CLI is .
  • You have access to a browser on a separate machine (for example, your laptop) to complete the authorization step.

​
How it works

The standard box login command opens a browser on the same machine and starts a local callback server to receive the authorization response automatically. In headless environments, neither is possible. The --code flag changes the login flow:
  • The CLI prints an authorization URL instead of opening a browser.
  • No local callback server is started.
  • After you authorize in a browser on another machine, you manually copy the resulting code and state back into the CLI.

​
Authenticate

​
Step 1: Start login with the --code flag

On the headless machine, run: 
box login --code
The CLI prints an authorization URL and waits for input.
You can combine --code with any other box login options. For example, to authenticate with a custom Box platform app, provide your Client ID and Client Secret when prompted.

​
Step 2: Authorize in a browser on another machine

Copy the authorization URL that the CLI printed, then open it in a browser on a machine that has one. Sign in to Box and select Grant Access to Box.

​
Step 3: Copy the code and state from the redirect URL

After you grant access, the browser redirects to a localhost callback URL. Because no callback server is running on the headless machine, the page does not load and the browser displays a connection error. This is expected. Look at the URL in the browser’s address bar. It contains the values you need: 
http://localhost:3000/callback?state=AUTHORIZATION_STATE&code=CODE_VALUE
Copy the values of code and state from this URL.

​
Step 4: Enter the codes in the CLI

Return to the terminal on the headless machine and paste the code and state values when the CLI prompts for them. After the CLI confirms successful authentication, you are ready to run commands.

​
Step 5: Verify the setup

box users:get me
If authentication was successful, the CLI returns information about your Box user account.

​
Using --code on a machine with a browser

The --code flag is intended for headless environments. If you use it on a machine that has a browser:
  • The CLI still prints the authorization URL.
  • After you authorize, the browser redirects to the callback URL. Because --code skips starting the local callback server, the redirect page does not load and the browser shows a connection error.
  • The CLI continues to wait for you to manually enter the code and state values, just as it would in a headless environment.
If a browser is available on the same machine, use box login without --code for a smoother experience.