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. Both keys default to off and are 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 resolve and githits code diff and the local stdio MCP server registers resolve_target and code_diff. tools is a strict boolean; quoted strings are rejected. With the setting absent or false, the commands are hidden from help and explicit invocations are rejected before authentication or network startup with the config path GitHits read and the enable snippet.

​
report_tool_issues

​
string
Optional. Accepted values are "experimental" (covers only resolve_target and code_diff) and "all" (covers any GitHits tool while the experimental suite is active). Omit the field for reporting-off, which is the default.Reporting changes agent guidance only: GitHits never sends feedback automatically. When enabled, the local quick_start guide allows one concise, redacted accepted: false feedback call per distinct observed issue and requires the exact tool name. Credentials, personal or private data, proprietary content, file bodies, and large outputs must not be included.The value is dormant when tools = false, but invalid values and types are still rejected by strict config-consuming paths.

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