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

# Authentication special cases

> Handle GitHits authentication manually for CI, headless machines, custom storage, and troubleshooting.

For normal local setup, `npx githits@latest init` handles authentication automatically. You only need this page for CI, headless machines, custom credential storage, or troubleshooting.

<Tabs>
  <Tab title="Browser OAuth (recommended)">
    Browser OAuth is the recommended method for local development. It opens a secure login flow in your browser and stores the resulting credentials in your system keychain so they refresh automatically.

    **Log in**

    ```bash theme={null}
    npx githits@latest login
    ```

    This opens your browser to the GitHits OAuth page. Sign in or create an account, authorize the app, and your browser redirects back. The CLI confirms when authentication is complete.

    **Useful flags**

    | Flag            | What it does                                                                                                            |
    | --------------- | ----------------------------------------------------------------------------------------------------------------------- |
    | `--no-browser`  | Prints a login URL instead of opening a browser. Use this for SSH sessions, containers, or other headless environments. |
    | `--force`       | Re-authenticates even if you are already logged in.                                                                     |
    | `--port <port>` | Uses a specific port for the local OAuth callback server.                                                               |

    **Example: headless login**

    ```bash theme={null}
    npx githits@latest login --no-browser
    ```

    The CLI prints a URL you can open on any device. After you complete login there, the CLI in your headless session receives the token automatically.
  </Tab>

  <Tab title="API token">
    For CI pipelines, automation scripts, and environments where browser login isn't practical, set the `GITHITS_API_TOKEN` environment variable.

    ```bash theme={null}
    export GITHITS_API_TOKEN=ghi-your-token-here
    ```

    When this variable is set, GitHits uses the token directly and skips the keychain. You can generate an API token from your account at [githits.com](https://githits.com).

    **Example: CI environment variable**

    ```bash theme={null}
    GITHITS_API_TOKEN=ghi-your-token-here npx githits@latest auth status
    ```

    For CI systems, set the variable as a secret in your CI provider rather than hardcoding it in scripts.

    <Tip>
      API tokens are the recommended approach for all non-interactive environments. They require no keychain access and work in any shell without additional setup.
    </Tip>
  </Tab>
</Tabs>

## Keychain storage

When you use browser OAuth, GitHits stores your credentials in the system keychain by default. The keychain used depends on your operating system:

| Platform | Keychain                                      |
| -------- | --------------------------------------------- |
| macOS    | Keychain Access                               |
| Windows  | Credential Manager                            |
| Linux    | Secret Service (e.g., GNOME Keyring, KWallet) |

GitHits reads from the keychain only when it actually needs the token — for example, during a tool call, a token refresh, or when you run `npx githits@latest auth status`. A small non-secret metadata file is written alongside credentials so routine startup checks do not need to hit the keychain.

On macOS you may see a prompt: **"githits wants to access ... in your keychain"**. Choose **Always Allow** if you trust the installed `githits` CLI. This is a macOS system prompt that GitHits cannot customize.

## File storage mode

If keychain prompts keep appearing even after choosing **Always Allow**, or if you are on a system without a keychain backend, you can switch OAuth credential storage to file mode.

<Warning>
  File mode stores OAuth credentials as plain JSON files. They are written with private permissions, but they are not encrypted. Any process running as your operating-system user can read them. Use file mode only on machines where you trust local user-account access. For CI and automation, use `GITHITS_API_TOKEN` instead.
</Warning>

**Option 1: Config file (persistent)**

Set `storage = "file"` in your GitHits config file:

<CodeGroup>
  ```toml macOS / Linux theme={null}
  # ~/.config/githits/config.toml
  # (or $XDG_CONFIG_HOME/githits/config.toml)
  [auth]
  storage = "file"
  ```

  ```toml Windows theme={null}
  # %APPDATA%\githits\config.toml
  [auth]
  storage = "file"
  ```
</CodeGroup>

The config directory may be empty until you create `config.toml`. Create it if it does not already exist.

**Option 2: Environment variable (one session)**

```bash theme={null}
GITHITS_AUTH_STORAGE=file npx githits@latest login --force
```

This opts into file storage for a single login without changing your config.

## Check authentication status

At any time, you can inspect your current auth setup:

```bash theme={null}
npx githits@latest auth status
```

This shows whether you are authenticated, where credentials are sourced from (keychain, file, or environment variable), and token expiry details when available.

## Log out

To remove stored credentials:

```bash theme={null}
npx githits@latest logout
```

This deletes the locally stored tokens. If you used `npx githits@latest init` to configure your coding tools, `logout` removes credentials only — your MCP configuration is preserved. Run `npx githits@latest init uninstall` separately if you want to remove the MCP configuration as well.