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

For HTTP requests and the browser playground, see [API authentication](/api/authentication). The storage guidance below applies to the CLI's credentials.

<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 callback still listens on the machine running the CLI. If the browser is on another computer, choose a fixed callback port and forward it over SSH:

    ```bash Remote host theme={null}
    npx githits@latest login --no-browser --port 8765
    ```

    ```bash Browser machine theme={null}
    ssh -N -L 8765:127.0.0.1:8765 user@remote-host
    ```

    Keep the tunnel open while you open the printed sign-in URL. Replace `user@remote-host` with your SSH destination.
  </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 create an API token in [your token settings](https://app.githits.com/settings/tokens).

    **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 uninstall` separately if you want to remove the MCP configuration as well.

## Terms of Service acceptance

Authenticated requests can return `TERMS_ACCEPTANCE_REQUIRED` when your account must accept the current GitHits Terms of Service. The CLI and local stdio MCP return a clear remediation command instead of retrying indefinitely:

```bash theme={null}
npx githits@latest settings terms accept
```

Hosted MCP clients can direct you to the browser acceptance page instead. Review the current [Terms of Service](https://githits.com/legal/terms-of-service/) before accepting.

### Check your current status

```bash theme={null}
npx githits@latest settings terms
```

Use `--json` to return the `terms_required` field as JSON.

### Accept from the CLI

The acceptance command asks for confirmation in an interactive terminal. Pass `--yes` only after you have reviewed the terms:

```bash theme={null}
npx githits@latest settings terms accept --yes
```

For machine-readable output, add `--json`. The response includes `accepted`, `token_refreshed`, and the updated settings object.

After acceptance, OAuth sessions force-refresh so later requests carry the updated terms state. If acceptance succeeds but refresh fails, run `npx githits@latest login --force` before retrying.

Opaque `GITHITS_API_TOKEN` credentials are not refreshed. GitHits checks their updated acceptance state on the next request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.