---
title: "CLI authentication"
description: "Sign the Bucky CLI in with your browser, sign in headlessly for scripts and CI, and keep separate profiles for you and your agents."
last_updated: "2026-10-04"
---

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](https://www.buckybuild.com) first.

## Sign in with your browser

```bash
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:

```bash
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:

```bash
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:

```bash
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.

<Callout type="warn">
  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.
</Callout>

## 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.

```bash
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 `_`.

| Profile             | Saved 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](/docs/cli/safe-writes#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](/docs/cli/agents).

## Developer API keys are separate

`bucky keys create` makes a developer API key for the [HTTP API](/docs/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](/docs/mcp/connect)).


## Sitemap

See the full [sitemap](/sitemap.md) for all pages.