Install the CLI and run operations

You work with devboxes through operations, for example sessions.dispatch to start a task. The devboxes CLI finds operations and runs them. The CLI reference lists its commands and options.

Install the CLI

curl -fsSLO https://devboxes.ai/install
printf "%s  install\n" 07727182ac5362fe5345beb5b88999a4973b5a6c127acf205e3540c419977b14 | $(command -v sha256sum || echo shasum -a 256) -c - && sh install
devboxes signup

Sign in

devboxes signup creates your account and asks how:

• Choose GitHub or Google, and the CLI shows a link and a short code. Open the link, check that the page shows the same code, and approve. You're signed in.
• Choose email and password, and devboxes emails you a six-digit code. Type it when the CLI asks to finish creating your account. You're signed in.

If GitHub or Google has not verified your email address there, create the account with your email and a password instead.

On another machine, or after devboxes logout, run:

devboxes login

It asks how you want to sign in: with GitHub or Google as above, with a six-digit code that devboxes emails you, or with your password. Type the code when the CLI asks. The code works once and expires after 5 minutes.

To choose the method up front, for example from a coding agent, add its flag:

devboxes signup --github
devboxes signup --google
printf '%s' "$PASSWORD" | devboxes signup --email [email protected] --password-stdin
devboxes login --github
devboxes login --google
devboxes login --email [email protected]

Outside a terminal, devboxes signup --email and devboxes login --email send the code and stop. Run the same command again on the same computer with the code on stdin to finish:

printf '%s' "$CODE" | devboxes signup --email [email protected] --code-stdin
printf '%s' "$CODE" | devboxes login --email [email protected] --code-stdin

Outside a terminal and with no flag, the CLI lists the sign-in methods and does not wait for an answer. A coding agent can then ask you which one to use and run the command again with your choice.

Sign in with a password and two-factor authentication

An account created with GitHub or Google has no password. To set one, or to replace a forgotten one, open app.devboxes.ai/reset-password and enter your email. devboxes emails you a link to a page where you choose the password. Afterwards, devboxes login offers email and password, and scripts pipe the password into devboxes login --email [email protected] --password-stdin.

With a password, you can turn on two-factor authentication through devboxes auth /two-factor/enable. Password sign-in then asks for the code from your authenticator app, a backup code, or a code devboxes emails to you. devboxes also refuses email-code sign-in for your account, so every email sign-in needs the second factor. GitHub and Google sign-in rely on the provider's own security. Every two-factor change, from turning it on or off to new backup codes, needs a sign-in from the last ten minutes, by any method your account has. You can't remove the password while two-factor authentication is on.

Find an operation

devboxes commands

The output lists the operations by name, one per line, with what they do. The operations reference has the same list, grouped by topic.

See what an operation takes

devboxes describe sessions.dispatch

You get the fields that the input needs and the fields of the result.

Run an operation

In a terminal, run the operation by its name, and the CLI asks for the input field by field:

devboxes invoke sessions.dispatch

For a field such as organizationId or projectId, the CLI offers a choice from your Organizations or Projects. It hides what you type for a secret, such as a key or a token, and offers the optional fields last. When the task needs Blueprint inputs or an issue that you didn't give, the CLI asks for all of them and sends the operation again.

To give the whole input at once, write it as JSON in a file:

{ "name": "My team", "slug": "my-team" }

Run the operation with that file:

devboxes invoke organizations.create --input @organization.json

The CLI prints the result. data holds what the operation returns, here the new Organization with its id. An Organization name has at most 18 characters.

Changes that need a recent sign-in

An operation that spends money, changes who can do what, hands over a credential, or can't be undone runs only within 10 minutes of signing in. After that, the CLI asks you to sign in again in the terminal, then sends the same operation once more. With --json or outside a terminal, it fails with SESSION_NOT_FRESH: run devboxes login, then repeat the operation.

Use the CLI in scripts

Add --json to get results and errors as one line of JSON:

devboxes --json invoke organizations.create --input @organization.json

To read the input from stdin, use --input -. Outside a terminal, or with --json, devboxes invoke fails with INPUT_REQUIRED unless you pass --input.