Skip to main content
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. For HTTP requests and the browser playground, see API authentication. The storage guidance below applies to the CLI’s credentials.
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
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 flagsExample: headless login
The callback still listens on the machine running the CLI. If the browser is on another computer, choose a fixed callback port and forward it over SSH:
Remote host
Browser machine
Keep the tunnel open while you open the printed sign-in URL. Replace user@remote-host with your SSH destination.

​
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: 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:
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)
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:
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:
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 uninstall separately if you want to remove the MCP configuration as well.

​
Terms of Service acceptance

Authenticated requests can return TERMS_ACCEPTANCE_REQUIRED when your account must accept the current GitHits Terms of Service. The CLI and local stdio MCP return a clear remediation command instead of retrying indefinitely:
Hosted MCP clients can direct you to the browser acceptance page instead. Review the current Terms of Service before accepting.

​
Check your current status

Use --json to return the terms_required field as JSON.

​
Accept from the CLI

The acceptance command asks for confirmation in an interactive terminal. Pass --yes only after you have reviewed the terms:
For machine-readable output, add --json. The response includes accepted, token_refreshed, and the updated settings object. After acceptance, OAuth sessions force-refresh so later requests carry the updated terms state. If acceptance succeeds but refresh fails, run npx githits@latest login --force before retrying. Opaque GITHITS_API_TOKEN credentials are not refreshed. GitHits checks their updated acceptance state on the next request.