Skip to main content
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

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

​
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
Then re-authenticate to write credentials in file mode:
You can also switch for a single login without editing the config file:
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.

​
The [experimental] section

The [experimental] section opts into the experimental tools that ship with the GitHits CLI and its local stdio MCP server. The setting defaults to off and is ignored by the hosted MCP at https://mcp.githits.com, plugin and extension installs, Cursor’s remote setup, and the public @githits/mcp server API.
~/.config/githits/config.toml

​
tools

​
boolean
default:"false"
When true, the CLI exposes githits research (with its githits ask alias), and the local stdio MCP server registers research. Quoted strings are rejected. When absent or false, Research is hidden from help and rejected before authentication or network startup.
resolve_target and githits resolve are available by default from 0.27.0. code_diff and githits code diff are available by default from 0.26.0. Neither requires this setting.

​
The [skills] section

From CLI 0.26.0, local MCP startup refreshes older, unchanged GitHits-managed githits-mcp skills in user roots and project roots under its startup directory. It does not install missing skills or replace edited, unrecognized, or newer content. Hosted MCP does not refresh local files. Disable refresh with:
auto_update defaults to true and must be a boolean. A non-empty GITHITS_DISABLE_SKILL_UPDATE also disables refresh. Invalid settings skip refresh with a warning; MCP startup continues. Explicit githits init still installs and repairs skills.

​
Checking your current configuration

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