Skip to main content

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.

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

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

​
The [auth] section

The [auth] section controls how OAuth credentials are stored on disk.
~/.config/githits/config.toml
[auth]
storage = "keychain"

​
storage

​
storage
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.

​
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:
~/.config/githits/config.toml
[auth]
storage = "file"
Then re-authenticate to write credentials in file mode: 
npx githits@latest login --force
You can also switch for a single login without editing the config file: 
GITHITS_AUTH_STORAGE=file npx githits@latest login --force
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.

​
Checking your current configuration

Run npx githits@latest auth status to see which storage backend is active and where credentials are stored: 
npx githits@latest auth status
The output includes the storage location so you can confirm whether keychain or file mode is in effect.