Skip to main content
Docs

CLI authentication

Sign the Bucky CLI in with your browser, sign in headlessly for scripts and CI, and keep separate profiles for you and your agents.

The CLI acts as a signed-in Bucky user. It can see and change only what that user can in the web app. There is no service account and no admin mode.

The CLI signs in to existing accounts only. Create your account at buckybuild.com first.

Sign in with your browser

bucky auth login

In an interactive terminal, this opens your browser to the Bucky sign-in page. Sign in as you normally do (Google or email), approve the CLI, and return to the terminal. The CLI waits up to two minutes for the browser to finish.

By default the CLI signs in to https://buckybuild.com. To use a different Bucky deployment, pass --api-url or set BUCKY_API_URL. Remote deployments must use HTTPS.

Check where you are signed in:

bucky auth status   # profile, token source, and expiry; no network call
bucky auth whoami   # asks Bucky who you are
bucky auth logout   # removes the saved session for this profile

If a command reports that your session has expired, run bucky auth login again.

Sign in without a browser

Scripts, CI, and --json runs never open a browser or prompt. Use one of these instead.

Email and password from the environment:

BUCKY_EMAIL=you@example.com BUCKY_PASSWORD=... bucky --json auth login

In an interactive terminal, bucky auth login --email you@example.com asks for the password without echoing it.

An existing token piped on standard input, so it never lands in shell history:

printf %s "$ACCESS_TOKEN" | bucky --json auth login --access-token-stdin
printf %s "$REFRESH_TOKEN" | bucky --json auth login --refresh-token-stdin

A token for one command only: set BUCKY_ACCESS_TOKEN. The CLI uses it ahead of any saved session, and never saves or refreshes it.

When a headless login is missing a value, the CLI returns one AUTH_INPUT_MISSING error instead of waiting for input.

Don't pass passwords or tokens as command-line flags. They end up in shell history and process lists. The flags still work but print a deprecation warning.

Profiles

A profile is a separate saved session. Use one for yourself and another for a coding agent, so the agent never uses your personal login.

bucky --profile agent auth login
bucky --profile agent projects list
BUCKY_PROFILE=agent bucky projects list   # same thing

Profile names are 1–40 letters, digits, -, or _.

ProfileSaved at
Default${XDG_CONFIG_HOME:-~/.config}/bucky/config.json
Named, e.g. agent${XDG_CONFIG_HOME:-~/.config}/bucky/profiles/agent.json

Profile files are readable only by your user. Each profile also keeps its own mutation receipts.

For agents, sign the profile in as a dedicated Bucky user that is a member of only the projects the agent should work on. See Coding agents.

Developer API keys are separate

bucky keys create makes a developer API key for the HTTP API. Keys are for the API only. The CLI itself always signs in as a user, and MCP clients use their own sign-in (MCP).

Last updated on