Authentication special cases

Handle GitHits authentication manually for CI, headless machines, custom storage, and troubleshooting.

For normal local setup, npx githits@latest init handles authentication automatically. You only need this page for CI, headless machines, custom credential storage, or troubleshooting.

Browser OAuth (recommended)

Browser OAuth is the recommended method for local development. It opens a secure login flow in your browser and stores the resulting credentials in your system keychain so they refresh automatically.

Log in

npx githits@latest login

This opens your browser to the GitHits OAuth page. Sign in or create an account, authorize the app, and your browser redirects back. The CLI confirms when authentication is complete.

Useful flags

Flag	What it does
--no-browser	Prints a login URL instead of opening a browser. Use this for SSH sessions, containers, or other headless environments.
--force	Re-authenticates even if you are already logged in.
--port <port>	Uses a specific port for the local OAuth callback server.

Example: headless login

npx githits@latest login --no-browser

The CLI prints a URL you can open on any device. After you complete login there, the CLI in your headless session receives the token automatically.

API token

For CI pipelines, automation scripts, and environments where browser login isn’t practical, set the GITHITS_API_TOKEN environment variable.

export GITHITS_API_TOKEN=ghi-your-token-here

When this variable is set, GitHits uses the token directly and skips the keychain. You can generate an API token from your account at githits.com.

Example: CI environment variable

GITHITS_API_TOKEN=ghi-your-token-here npx githits@latest auth status

For CI systems, set the variable as a secret in your CI provider rather than hardcoding it in scripts.

API tokens are the recommended approach for all non-interactive environments. They require no keychain access and work in any shell without additional setup.

Keychain storage

When you use browser OAuth, GitHits stores your credentials in the system keychain by default. The keychain used depends on your operating system:

Platform	Keychain
macOS	Keychain Access
Windows	Credential Manager
Linux	Secret Service (e.g., GNOME Keyring, KWallet)

GitHits reads from the keychain only when it actually needs the token — for example, during a tool call, a token refresh, or when you run npx githits@latest auth status. A small non-secret metadata file is written alongside credentials so routine startup checks do not need to hit the keychain.

On macOS you may see a prompt: “githits wants to access … in your keychain”. Choose Always Allow if you trust the installed githits CLI. This is a macOS system prompt that GitHits cannot customize.

File storage mode

If keychain prompts keep appearing even after choosing Always Allow, or if you are on a system without a keychain backend, you can switch OAuth credential storage to file mode.

File mode stores OAuth credentials as plain JSON files. They are written with private permissions, but they are not encrypted. Any process running as your operating-system user can read them. Use file mode only on machines where you trust local user-account access. For CI and automation, use GITHITS_API_TOKEN instead.

Option 1: Config file (persistent)

Set storage = "file" in your GitHits config file:

macOS / Linux

# ~/.config/githits/config.toml
# (or $XDG_CONFIG_HOME/githits/config.toml)
[auth]
storage = "file"

The config directory may be empty until you create config.toml. Create it if it does not already exist.

Option 2: Environment variable (one session)

GITHITS_AUTH_STORAGE=file npx githits@latest login --force

This opts into file storage for a single login without changing your config.

Check authentication status

At any time, you can inspect your current auth setup:

npx githits@latest auth status

This shows whether you are authenticated, where credentials are sourced from (keychain, file, or environment variable), and token expiry details when available.

Log out

To remove stored credentials:

npx githits@latest logout

This deletes the locally stored tokens. If you used npx githits@latest init to configure your coding tools, logout removes credentials only — your MCP configuration is preserved. Run npx githits@latest init uninstall separately if you want to remove the MCP configuration as well.