> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# murmur login

> Sign in to Murmur with your gh CLI session or the GitHub device flow and store the identity credential in the OS keychain.

Signs you in to Murmur and stores the identity credential in the OS keychain. It runs only the sign-in step of [`murmur setup`](/cli/setup), so use it to re-authenticate or to switch accounts in a repo that is already set up. It does not touch GitHub access, tenant discovery, or your developer profile.

Re-runs are cheap: a stored identity that is still valid is reused, with no new browser sign-in.

## Synopsis

```bash theme={null}
murmur login [--identity NAME]
```

The command takes no positional arguments.

## Arguments

| Name | Type | Required | Description |
| - | - | - | - |
| `--identity` | string | no | Named keychain identity to sign in as. Saved to `murmur.local.yaml` as `identity_name`. Defaults to the repo's current selection, or `default`. Names match `[a-z0-9][a-z0-9_-]{0,31}`. |

## What it does

1. Asks how to sign you in:
   * **Use your gh CLI login** (recommended). Verified in place. If the gh token cannot serve as your identity, sign-in falls back to Murmur's GitHub App.
   * **Sign in with Murmur's GitHub App** using a one-time browser code (device flow).
2. Stores the credential in the OS keychain under the selected identity, when one needs storing.
3. Records the identity name and your GitHub username in `.murmur/murmur.local.yaml`.

When `MURMUR_IDENTITY_TOKEN` and `MURMUR_AUTH_METHOD=github_oauth` are set, the command uses that token instead of prompting. A personal access token cannot serve as Murmur identity.

## Output

The last line on stderr confirms the sign-in. Which one depends on how you signed in:

```
  ✓ Signed in as "alice" (identity "default", murmur-identity / default@api.murmur.dev:9090).
  ✓ Signed in as "alice" via your gh CLI session — resolved live, no keychain credential stored.
  ✓ Signed in as "alice" via MURMUR_IDENTITY_TOKEN — no keychain credential stored.
```

## Examples

### Re-authenticate

```bash theme={null}
murmur login
```

### Sign in as a second account

```bash theme={null}
murmur login --identity work
```

## Errors

| Code | Meaning | What to do |
| - | - | - |
| none | `login accepts no positional arguments — did you mean --identity <arg>?` | Pass the identity name with `--identity`. |
| none | ``login needs an existing murmur config — run `murmur setup` to bootstrap: ...`` | Run [`murmur setup`](/cli/setup) first. |
| none | `login needs a repo config (.murmur/murmur.yaml) to record the sign-in in ...` | Run [`murmur setup`](/cli/setup) in the repo. With `MURMUR_API_KEY` set, the API key is the credential and login is not needed. |
| none | `MURMUR_IDENTITY_TOKEN and MURMUR_AUTH_METHOD must be set together ...` | Set both variables, or neither. |
| none | `murmur login manages the GitHub identity credential, but this run's identity comes from MURMUR_AUTH_METHOD="<method>" ...` | Unset the variable pair to sign in with GitHub. |
| none | `MURMUR_IDENTITY_TOKEN is a personal access token, which cannot serve as murmur identity ...` | Unset it to use the device flow, or supply a token minted by Murmur's GitHub App. |
| none | `signed in as "<login>", but recording the selection in murmur.local.yaml failed ...` | Make the file writable, then run `murmur login --identity <name>` again. The stored credential is reused without a new browser sign-in. |

## Related

* [`murmur logout`](/cli/logout): remove the stored identity
* [`murmur setup`](/cli/setup): bootstrap a repo
* [Authentication](/security/authentication): how Murmur identifies you
* [Local overlays](/configuration/local-overlays): `murmur.local.yaml`