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

# GitHits CLI environment variable reference

> All environment variables supported by the GitHits CLI, including authentication overrides and diagnostic options.

The GitHits CLI reads several environment variables at startup. You can use them to authenticate without a browser, switch credential storage modes, or suppress update notifications.

| Variable                       | Purpose                                                    | Default    |
| ------------------------------ | ---------------------------------------------------------- | ---------- |
| `GITHITS_API_TOKEN`            | API token for authentication (format: `ghi-...`)           | —          |
| `GITHITS_AUTH_STORAGE`         | Override OAuth storage mode: `keychain` or `file`          | `keychain` |
| `GITHITS_TELEMETRY`            | Emit end-of-run timing spans to stderr for local profiling | —          |
| `GITHITS_DISABLE_UPDATE_CHECK` | Disable npm latest-version update notices                  | —          |

***

## GITHITS\_API\_TOKEN

Set an API token to authenticate without browser OAuth. This is the recommended approach for CI pipelines, automation scripts, and headless environments where a browser login isn't practical.

Tokens follow the format `ghi-...` and can be generated from your [GitHits account settings](https://githits.com).

When `GITHITS_API_TOKEN` is set, the CLI skips local OAuth storage entirely. You can verify this with `npx githits@latest auth status`, which reports the credential source.

<CodeGroup>
  ```bash Shell export theme={null}
  export GITHITS_API_TOKEN=ghi-your-token-here
  npx githits@latest auth status
  ```

  ```bash Inline (single command) theme={null}
  GITHITS_API_TOKEN=ghi-your-token-here npx githits@latest auth status
  ```

  ```yaml GitHub Actions theme={null}
  - name: Run GitHits
    env:
      GITHITS_API_TOKEN: ${{ secrets.GITHITS_API_TOKEN }}
    run: npx githits@latest example "retry with exponential backoff"
  ```
</CodeGroup>

<Note>
  `GITHITS_API_TOKEN` takes precedence over stored OAuth credentials. If both are present, the environment variable is used.
</Note>

***

## GITHITS\_AUTH\_STORAGE

Override the OAuth credential storage mode for a single process or for all GitHits commands in the current shell session.

* `keychain` (default) — stores OAuth credentials in the system keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service).
* `file` — stores OAuth credentials as JSON files in the GitHits config directory.

Use `file` mode in SSH sessions, CI environments, or when persistent keychain prompts remain even after granting access.

<CodeGroup>
  ```bash Login with file storage (one-off) theme={null}
  GITHITS_AUTH_STORAGE=file npx githits@latest login --force
  ```

  ```bash Set for the current shell session theme={null}
  export GITHITS_AUTH_STORAGE=file
  npx githits@latest login
  ```
</CodeGroup>

<Warning>
  File storage is not encrypted. Any process running as your OS user can read the stored tokens. For CI and automation, use `GITHITS_API_TOKEN` instead.
</Warning>

## GITHITS\_TELEMETRY

When set to any non-empty value, the CLI emits end-of-run timing spans to stderr. Use this for local profiling and performance investigation. The output goes to stderr only and does not affect stdout.

```bash theme={null}
GITHITS_TELEMETRY=1 npx githits@latest example "connect to redis"
```

***

## GITHITS\_DISABLE\_UPDATE\_CHECK

When set to any non-empty value, suppresses the npm latest-version check and update notice that the CLI prints when a newer version is available. Useful in CI environments where the notice would pollute log output.

```bash theme={null}
export GITHITS_DISABLE_UPDATE_CHECK=1
```