> ## 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 configuration: config.toml reference

> Reference for the GitHits CLI config file: location, the [auth] section, storage modes, and when to use file storage over the system keychain.

The GitHits CLI reads a TOML configuration file at startup. The config file is optional — the CLI works without it, using sensible defaults. You only need to create it when you want to change a setting, such as switching from keychain to file-based OAuth storage.

## Config file location

| Platform                     | Path                                   |
| ---------------------------- | -------------------------------------- |
| macOS / Linux                | `~/.config/githits/config.toml`        |
| macOS / Linux (XDG override) | `$XDG_CONFIG_HOME/githits/config.toml` |
| Windows                      | `%APPDATA%\githits\config.toml`        |

The config directory may be empty on a fresh install. GitHits writes auth metadata to that directory automatically, but it does not create `config.toml` for you. Create the file yourself if you need to override any defaults.

<Note>
  On older macOS installs, GitHits may have stored auth data in `~/Library/Application Support/githits`. The CLI still reads that location for migration, but all new auth config and file storage now uses `~/.config/githits`.
</Note>

***

## The \[auth] section

The `[auth]` section controls how OAuth credentials are stored on disk.

```toml ~/.config/githits/config.toml theme={null}
[auth]
storage = "keychain"
```

### storage

<ParamField body="storage" type="string" default="keychain">
  Controls the OAuth credential storage backend. Accepted values:

  * `"keychain"` — stores credentials in the system keychain (macOS Keychain Access, Windows Credential Manager, Linux Secret Service). This is the default and the most secure option.
  * `"file"` — stores credentials as JSON files in the GitHits config directory. The files are written with private permissions where the platform supports it, but they are not encrypted.
</ParamField>

***

## Keychain storage (default)

With `storage = "keychain"`, GitHits reads and writes OAuth credentials through the operating system's credential manager. This means:

* On **macOS**, credentials are stored in Keychain Access. The first access may show a system prompt — choose **Always Allow** to prevent repeated prompts.
* On **Windows**, credentials are stored in Credential Manager.
* On **Linux**, credentials are stored in the available Secret Service or keyring backend.

GitHits also writes a small non-secret metadata file to the config directory so that routine startup checks do not need to hit the keychain on every run. The keychain is only read when GitHits actually needs the token — for example during a tool call, a token refresh, `npx githits@latest auth status`, or a login check after metadata is stale or expired.

***

## File storage

With `storage = "file"`, GitHits stores OAuth credentials as JSON files in the config directory instead of the system keychain. This is useful when:

* You are connecting over SSH and don't have access to a graphical keychain prompt.
* You are running in a CI or headless environment where no keychain is available.
* The system keychain keeps showing prompts even after granting access.

To switch to file storage, create or edit `config.toml`:

```toml ~/.config/githits/config.toml theme={null}
[auth]
storage = "file"
```

Then re-authenticate to write credentials in file mode:

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

You can also switch for a single login without editing the config file:

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

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

***

## Checking your current configuration

Run `npx githits@latest auth status` to see which storage backend is active and where credentials are stored:

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

The output includes the storage location so you can confirm whether keychain or file mode is in effect.