Install on macOS or Linux. On Windows, run the same command in WSL.
shell
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/driver-ai/cli/releases/latest/download/driver-installer.sh | sh
Sign in with a personal access token from the Driver web app, then check what is set up and what to do next.
shell
driver auth login
driver status
Use --output json for scripts and agents. Use driver <command> --help for help in your terminal. See the release downloads for this version.
Global options
These options are available to every command.
Option
Description
Default
--profile <NAME>
Use this saved profile for this command only (driver auth switch changes the default)
Environment: DRIVER_PROFILE
None
--output <OUTPUT>
Output format
Environment: DRIVER_OUTPUT
Accepted values
table
json
table
-v, --verbose
Log each request to stderr (method, path, status; never the token)
Environment: DRIVER_VERBOSE
false
Environment variables
Variable
Meaning
DRIVER_TOKEN
A personal access token, used instead of any profile; refused together with --profile or DRIVER_PROFILE
DRIVER_PROFILE
The profile to use, like --profile
DRIVER_API_URL
The API for driver auth login and for DRIVER_TOKEN (default https://api.us1.driverai.com). A saved profile keeps its own API; a different DRIVER_API_URL beside it is refused
DRIVER_OUTPUT
table (default) or json
DRIVER_VERBOSE
Log each request to stderr: method, path, status, size, time; never the token
DRIVER_CONFIG
The config file, instead of the default path (~/.config/driver/config.json)
DRIVER_WEB_APP_URL
The web app, for the links the CLI prints (default https://app.driverai.com); saved into the profile at login
DRIVER_GIT_TOKEN
The provider token for driver integration connect and token rotate, instead of the prompt
DRIVER_SCIM_TOKEN
The compound token for driver scim test, instead of the prompt
DRIVER_POLL_INTERVAL
Seconds between polls while waiting with --wait; fractions allowed
Output and errors
Use --output json for machine-readable output. Error details go to stderr.
Every failure is one object on stderr with --output json. status is 0 when the CLI raised the failure itself and the HTTP status when the API's error passed through.
context is null for a failure the CLI raised and an object for one the API answered.
Usage errors from the argument parser are plain text on stderr, even with --output json.
Choosing who a command runs as: DRIVER_TOKEN if set, else the profile --profile or DRIVER_PROFILE names, else the default profile. The refusals are usage errors (exit 2) with the codes profile_not_found, no_default_profile, api_url_mismatch, and token_with_profile.
No matching commands. Try a command name or option such as --wait.
driver auth
Sign in with a personal access token, see who you are, switch profiles, sign out
Subcommands
driver auth login Paste a personal access token from the web app and save it as a profile, which becomes the default. The API is DRIVER_API_URL, else the existing profile --profile names, else https://api.us1.driverai.com; --profile also names a new profile
driver auth logout Forget a saved profile: the default, or the one --profile names
driver auth login
Browser step
Paste a personal access token from the web app and save it as a profile, which becomes the default. The API is DRIVER_API_URL, else the existing profile --profile names, else https://api.us1.driverai.com; --profile also names a new profile
shell
driver auth login [--token-stdin] [--no-browser]
Who can run it
any member
Undo
driver auth logout
Usage notes and limits
Opens the web app's token page unless --no-browser, which prints the address instead. The token is read from DRIVER_TOKEN, from stdin with --token-stdin, or from a hidden prompt; it is checked with one read before it is saved. A machine key (drvm_…) is refused: the CLI signs in with a personal access token. Saves a profile (one person in one organization on one API) and makes it the default; never prompts for its name. Signing in again as the same person refreshes their profile; anyone else gets their own. The name is --profile, else the same person's existing profile, else the organization's slug with a word for any API but the default (acme, acme-dev, acme-local), plus the email's local part when someone else in the organization holds that name (acme-dev-mel), numbered when still taken. A given name that belongs to anyone else is refused.
Options
Option
Description
Default
--token-stdin
Read the token from stdin instead of a hidden prompt
false
--no-browser
Print the web app address instead of opening it
false
driver auth status
Read
Show who you are and the other saved profiles
shell
driver auth status
Who can run it
any member
Notes
Exits 3 when the token in use is expired or refused, after printing what it found.
driver auth switch
Local only
Make another saved profile the default
shell
driver auth switch <NAME>
Who can run it
any member
Undo
driver auth switch <the previous default>
Notes
Changes only which profile commands use by default; sends no request.
Arguments
Argument
Description
Default
<NAME>
Required
The profile's name, as driver auth status lists it
None
driver auth rename
Local only
Rename a saved profile
shell
driver auth rename <OLD> <NEW>
Who can run it
any member
Undo
driver auth rename <new> <old>
Notes
The default follows the rename. A name already taken is refused; names are letters, digits, -, _ and .
Arguments
Argument
Description
Default
<OLD>
Required
The profile's current name
None
<NEW>
Required
Its new name: letters, digits, -, _ and
None
driver auth logout
Local only
Forget a saved profile: the default, or the one --profile names
shell
driver auth logout
Who can run it
any member
Undo
driver auth login
Usage notes and limits
Forgets the profile only (the default, or the one --profile names); the token stays valid until it is revoked with driver token revoke <name>. Forgetting the default leaves the one remaining profile as the default, or none when several remain.
driver status
Read
What is set up for your organization, and what to do next
shell
driver status
Who can run it
any member
Notes
A member sees Integrations as organization admins only, and a line whose read the API refuses for their role (Codebases, Members, Balance) as n/a instead of a failure. The Still to do list is shown to organization admins.
driver doctor
Read
Diagnose the installation and the connection to Driver (prints no secrets)
shell
driver doctor
Who can run it
any member
Notes
Runs without a login and exits 0 whatever it finds: an unreachable API or a refused token is a line of the report. Prints the token's prefix only.
driver usage
Read
Your organization's usage balance, and recent charges with --charges
shell
driver usage [--charges]
Who can run it
any member
Notes
--charges needs an organization admin.
Options
Option
Description
Default
--charges
Also list the most recent charges (organization admins only)
false
driver completion
Local only
Print a shell completion script
shell
driver completion <SHELL>
Who can run it
any member
Notes
Prints the script to stdout; never opens a session.
Arguments
Argument
Description
Default
<SHELL>
Required
The shell to print the script for
Accepted values
bash
elvish
fish
powershell
zsh
None
driver mcp
Connect an agent or editor to Driver's MCP server
Subcommands
driver mcp setup Print how to add Driver's MCP server to a client (edits nothing, stores no token)
driver mcp setup
Local only
Print how to add Driver's MCP server to a client (edits nothing, stores no token)
shell
driver mcp setup --client <CLIENT>
Who can run it
any member
Notes
Prints instructions only: edits no client configuration and stores no token. Uses the API of the profile in use, or DRIVER_API_URL with DRIVER_TOKEN.
Whether personal access tokens are on, and how long they may last
shell
driver org tokens
Who can run it
any member
driver org visibility
Write
The default visibility of codebases connected from now on
shell
driver org visibility [--default <VISIBILITY>]
Who can run it
organization admin
Undo
driver org visibility --default <previous value>
Notes
Without --default this is a read any member can run. Setting the default needs an organization admin and applies to codebases connected from now on; existing codebases keep theirs.
GitHub: a GitHub App install, started from the web app
shell
driver integration connect github [--no-browser]
Who can run it
organization admin
Undo
none; uninstall the GitHub App from the web app's Integrations page
Notes
GitHub is connected by installing the GitHub App from the web app; the command opens that page unless --no-browser, then waits until the App is connected (up to 10 minutes). Ctrl-C stops waiting; run the command again to wait more.
Options
Option
Description
Default
--no-browser
Print the web app address instead of opening it
false
driver integration connect gitlab
Write
GitLab (gitlab.com, or --url for a self-managed instance)
The token is read from DRIVER_GIT_TOKEN, from stdin with --token-stdin, or from a hidden prompt. Connecting the same instance again adds a token to the existing integration. A token the provider refuses leaves nothing behind.
Options
Option
Description
Default
--url <URL>
The GitLab instance, e.g. https://gitlab.acme.dev
None
--name <NAME>
The integration's name (defaults from the instance)
None
--label <LABEL>
A label for the token (defaults to token-1, token-2, ...)
None
--token-stdin
Read the provider token from stdin instead of a hidden prompt
The token is read from DRIVER_GIT_TOKEN, from stdin with --token-stdin, or from a hidden prompt. Connecting the same workspace again adds a token to the existing integration. A token the provider refuses leaves nothing behind.
Options
Option
Description
Default
--workspace <SLUG>
Required
The Bitbucket workspace slug
None
--kind <KIND>
What kind of access token this is
Accepted values
workspace
project
repository
None
--label <LABEL>
A label for the token (defaults to token-1, token-2, ...)
None
--token-stdin
Read the provider token from stdin instead of a hidden prompt
The token is read from DRIVER_GIT_TOKEN, from stdin with --token-stdin, or from a hidden prompt. Connecting the same address again adds a token to the existing integration. A token the provider refuses leaves nothing behind. Pushes reach Driver once the webhook is created with driver integration webhook enable <name>.
Options
Option
Description
Default
--url <URL>
Required
The Bitbucket Data Center address, e.g. https://bitbucket.acme.internal
None
--name <NAME>
The integration's name (defaults from the address)
None
--kind <KIND>
What kind of HTTP access token this is
Accepted values
project
repository
None
--label <LABEL>
A label for the token (defaults to token-1, token-2, ...)
None
--token-stdin
Read the provider token from stdin instead of a hidden prompt
The token is read from DRIVER_GIT_TOKEN, from stdin with --token-stdin, or from a hidden prompt. One token per project: connecting another project of the same organization adds a token to the existing integration. A token the provider refuses leaves nothing behind.
Options
Option
Description
Default
--organization <ORG>
Required
The Azure DevOps organization: its name, or its dev.azure.com or visualstudio.com address
None
--project <PROJECT>
Required
The Azure DevOps project
None
--label <LABEL>
A label for the token (defaults to the project)
None
--token-stdin
Read the provider token from stdin instead of a hidden prompt
false
driver integration connect gerrit
Write
Gerrit (not supported in the CLI yet)
shell
driver integration connect gerrit
Who can run it
organization admin
Notes
Not available in this release; the command refuses with "The CLI doesn't support Gerrit yet." and exit 2. Supported: github, gitlab, bitbucket, bitbucket-dc, azure-devops.
Lists what the token can see and marks the repositories already connected. The GitHub App's repositories are not listed; connect them with driver codebase connect.
Arguments
Argument
Description
Default
<INTEGRATION>
Required
The integration: its name, <provider>/<name>, or its id
driver integration token rotate <integration> --label <label>, with the previous token
Notes
The new token is read from DRIVER_GIT_TOKEN, from stdin with --token-stdin, or from a hidden prompt, and is checked by listing the repositories it can see.
Arguments
Argument
Description
Default
<INTEGRATION>
Required
The integration: its name, <provider>/<name>, or its id
None
Options
Option
Description
Default
--label <LABEL>
Which token, when the integration has several
None
--token-stdin
Read the provider token from stdin instead of a hidden prompt
false
driver integration token remove
Destructive write
Remove a token; its codebases stay in Driver but stop updating
none; add a token again with driver integration connect <provider>
Notes
Codebases connected through the token stay in Driver but stop updating. The token and any webhook stay in the provider; delete them there.
Offers --yes to skip confirmation where applicable. Check the conditions above.
Arguments
Argument
Description
Default
<INTEGRATION>
Required
The integration: its name, <provider>/<name>, or its id
None
Options
Option
Description
Default
--label <LABEL>
Required
Which token
None
--yes
Skip the confirmation
false
driver integration remove
Destructive write
Remove an integration; its codebases stay in Driver but stop updating
shell
driver integration remove <INTEGRATION> [--yes]
Who can run it
organization admin
Undo
none; connect the provider again with driver integration connect <provider>
Notes
Its codebases stay in Driver but stop updating. The tokens and webhooks stay in the provider; delete them there. The GitHub App is not an integration here; uninstall it from the web app.
Offers --yes to skip confirmation where applicable. Check the conditions above.
Arguments
Argument
Description
Default
<INTEGRATION>
Required
The integration: its name, <provider>/<name>, or its id
None
Options
Option
Description
Default
--yes
Skip the confirmation
false
driver integration webhook
Read
How to set up the provider's webhook; enable and disable create it on Bitbucket Data Center
Prints the webhook secret in full, with the address and headers, for pasting into the provider. The integration is named by its name, <provider>/<name>, or its id.
Arguments
Argument
Description
Default
<INTEGRATION>
Required
The integration: its name, <provider>/<name>, or its id
Bitbucket Data Center only; other providers' webhooks are set up by hand, and driver integration webhook <integration> shows how. Refuses when the token already has a webhook.
Arguments
Argument
Description
Default
<INTEGRATION>
Required
The integration: its name, <provider>/<name>, or its id
Finds the repository through the connected integrations; --integration and --label pick one when several can see it. A repository already connected is reported, not connected twice. --wait polls until the code is fetched (every 10 s, up to 30 minutes unless --timeout); Ctrl-C stops watching while the fetch continues, and driver codebase connect <owner/repo> --wait resumes. Indexing is a separate step: driver index start.
Arguments
Argument
Description
Default
<OWNER/REPO>
Required
The repository as the provider names it, owner/repo
None
Options
Option
Description
Default
--integration <NAME>
Which integration, when the repository is visible through several
None
--label <LABEL>
Which token, when the integration has several
None
--wait
Wait until the code is fetched and the codebase is ready to index
driver codebase settings <codebase> with the previous values; driver codebase get shows them
Usage notes and limits
At least one flag is needed. --except and --also take at most 10 patterns each, every pattern 1 to 256 characters, checked before the request. --branches, --except, and --also need the multi-branch feature for the organization. --auto-update, --auto-commit-docs, and --force-all-pushes apply to git-connected codebases; an uploaded codebase has --visibility only.
Arguments
Argument
Description
Default
<CODEBASE>
Required
The codebase: owner/repo, its name, or its id
None
Options
Option
Description
Default
--visibility <VISIBILITY>
Who can see it: people granted access, or everyone in the organization
Accepted values
private Only people granted access
internal Everyone in the organization
None
--auto-update <WHEN>
How often pushes update the index
Accepted values
every-push
1h
2h
4h
1d
3d
1w
2w
4w
never
None
--auto-commit-docs <on|off>
Commit generated docs back to the repository
Accepted values
on
off
None
--force-all-pushes <on|off>
Index every push, even when the update policy would skip it
Accepted values
on
off
None
--branches <all|default>
Which branches Driver indexes: all of them, or only the default branch
Accepted values
all
default
None
--except <REGEX>
With --branches all: leave out branches matching this regex (repeatable)
Repeatable.
None
--also <REGEX>
With --branches default: also index branches matching this regex (repeatable)
none; an index that has started runs on Driver and spends the balance
Usage notes and limits
Estimates the cost, then asks to confirm (--yes skips it; without a terminal it refuses). --dry-run prints the estimate and starts nothing. Refuses when the organization's balance is short of the estimate. Without --branch the default branch is indexed, plus recently committed branches when the multi-branch feature is on. --wait polls until indexing finishes (every 10 s, up to 60 minutes unless --timeout); Ctrl-C stops watching while indexing continues, and driver index status <codebase> --wait resumes.
Offers --yes to skip confirmation where applicable. Check the conditions above.
Arguments
Argument
Description
Default
<CODEBASE>
Required
The codebase: owner/repo, its name, or its id
None
Options
Option
Description
Default
--branch <NAME>
A branch to index (repeatable; default: the web app's selection)
Repeatable.
None
--yes
Skip the confirmation
false
--dry-run
Show the estimate and start nothing
false
--wait
Wait until indexing finishes
false
--timeout <SECS>
Stop waiting after this many seconds
None
driver index status
Read
The indexing state of each branch
shell
driver index status <CODEBASE> [--branch <NAME>...] [--wait] [--timeout <SECS>]
Who can run it
any member
Usage notes and limits
Without --branch, shows 50 branches: the default branch first, then by most recent commit; name others with --branch, or find them with driver codebase branch list --search. --wait follows the branches being indexed; Ctrl-C stops watching, and driver index status <codebase> --wait resumes.
Arguments
Argument
Description
Default
<CODEBASE>
Required
The codebase: owner/repo, its name, or its id
None
Options
Option
Description
Default
--branch <NAME>
A branch to show (repeatable)
Repeatable.
None
--wait
Wait until the branches being indexed finish
false
--timeout <SECS>
Stop waiting after this many seconds
None
driver index list
Read
Past and current indexes of a branch, newest first
shell
driver index list <CODEBASE> [--branch <NAME>] [--limit <N>]
Who can run it
any member
Notes
Shows the 50 newest indexes of one branch unless --limit says otherwise.
driver member remove Remove members, with their tokens, grants, and team memberships
driver member list
Read
The organization's members, admins first
shell
driver member list [--role <ROLE>] [--search <TEXT>] [--limit <N>]
Who can run it
any member
Notes
Reads every page of members; --limit caps what is shown, not what is read.
Options
Option
Description
Default
--role <ROLE>
Only members with this role
Accepted values
admin
member
None
--search <TEXT>
Only members whose email or name contains this text
None
--limit <N>
Show at most this many
None
driver member invite
Write
Invite people by email; they get an email from Driver
shell
driver member invite <EMAIL>... [--role <ROLE>]
Who can run it
organization admin
Undo
driver invitation revoke <email>
Notes
An address that is already a member, or already invited and not expired, is skipped; an expired invitation is revoked and sent again. One --role applies to every address.
Arguments
Argument
Description
Default
<EMAIL>...
Required
An email address (one or more)
Repeatable.
None
Options
Option
Description
Default
--role <ROLE>
The role to invite them as (default member)
Accepted values
admin
member
None
driver member role
Write
Change a member's role
shell
driver member role <EMAIL> <ROLE>
Who can run it
organization admin
Undo
driver member role <email> <previous role>
Notes
You cannot change your own role, and the last organization admin cannot be made a member.
Arguments
Argument
Description
Default
<EMAIL>
Required
The member's email
None
<ROLE>
Required
The new role
Accepted values
admin
member
None
driver member remove
Destructive write
Remove members, with their tokens, grants, and team memberships
shell
driver member remove <EMAIL>... [--yes]
Who can run it
organization admin
Undo
none; invite them again with driver member invite <email> and grant their access again
Notes
Their tokens, codebase grants, and team memberships go with them. Members provisioned by SCIM are removed in the identity provider, not here. Asks to confirm unless --yes.
Offers --yes to skip confirmation where applicable. Check the conditions above.
The organization's teams (members see the teams they belong to)
shell
driver team list [--search <TEXT>] [--limit <N>]
Who can run it
any member
Notes
A member sees the teams they belong to; an organization admin sees all of them.
Options
Option
Description
Default
--search <TEXT>
Only teams whose name contains this text
None
--limit <N>
Show at most this many
None
driver team create
Write
Create a team
shell
driver team create <NAME>
Who can run it
organization admin
Undo
driver team remove <name>
Notes
The name must be unused in the organization.
Arguments
Argument
Description
Default
<NAME>
Required
The team's name
None
driver team remove
Destructive write
Remove teams
shell
driver team remove <TEAM>... [--yes]
Who can run it
organization admin
Undo
none; create it again with driver team create <name>, then add its members and grant its codebases again
Notes
Its members lose the access they had through it. A team provisioned by SCIM is removed in the identity provider, not here. Asks to confirm unless --yes.
Offers --yes to skip confirmation where applicable. Check the conditions above.
none; the connection cannot be removed or changed from Driver, contact support@driverai.com
Usage notes and limits
Refuses when single sign-on is already configured. From their next sign-in, everyone with an address at the given domains, including you, signs in through the identity provider; set it up with the values from driver sso metadata first, or they are locked out until support removes the connection. Asks to confirm unless --yes.
Offers --yes to skip confirmation where applicable. Check the conditions above.
Options
Option
Description
Default
--metadata-url <URL>
The identity provider's federation metadata URL
Cannot combine with: --metadata-file
None
--metadata-file <PATH>
A file with the identity provider's metadata XML (- reads stdin)
None
--domain <DOMAIN>
Required
An email domain whose users sign in through the provider (repeatable)
Turn on SCIM provisioning and print the token for your identity provider (shown once)
shell
driver scim enable [--yes]
Who can run it
organization admin
Undo
driver scim disable
Usage notes and limits
Needs single sign-on configured first. Prints two secrets once: the SCIM URL and the token for the identity provider; neither is shown again. When SCIM is already on, running it again issues a new token (the old one stops working) and resets the attribute mapping, after asking to confirm (--yes skips it).
Offers --yes to skip confirmation where applicable. Check the conditions above.
Options
Option
Description
Default
--yes
Skip the confirmation when SCIM is already on (this rotates the token)
false
driver scim disable
Destructive write
Turn off SCIM provisioning
shell
driver scim disable [--yes]
Who can run it
organization admin
Undo
driver scim enable, which issues a new token for the identity provider
Notes
The identity provider's token stops working at once. Asks to confirm unless --yes.
Offers --yes to skip confirmation where applicable. Check the conditions above.
Options
Option
Description
Default
--yes
Skip the confirmation
false
driver scim test
Read
Check that the identity provider's token reaches the SCIM endpoints
shell
driver scim test [--token-stdin]
Who can run it
organization admin
Notes
The token is read from DRIVER_SCIM_TOKEN, from stdin with --token-stdin, or from a hidden prompt. Probes the users and groups endpoints and exits 1 when either refuses the token.
Options
Option
Description
Default
--token-stdin
Read the SCIM token from stdin instead of a hidden prompt
