gritHEAD → docs/auth
Commands / RemotesMarkdown

grit auth

Sign in to GitButler Code, GitHub or a grit serve host, or save a username and token for any HTTPS host, so pushes and fetches just work.

grit auth [--token <token>]
grit auth <url> [--token <token>]
grit auth <url> --username <user> --token <token>
grit auth logout [<url>] [--dry-run]

Description

Signs you in and saves the token, so that grit push, grit fetch and grit clone work with private repositories over HTTPS.

Without a URL, grit auth signs in to GitButler Code, unless you run it inside a repository whose origin is on github.com: then it signs in to GitHub. GitButler Code signs in like a grit serve host: grit opens GitButler Code's sign-in page in your browser, you sign in with Google or your email address and approve the code, and grit saves the new token. Set the GRIT_DEFAULT_HOST environment variable to sign in to another grit server by default. grit auth https://github.com always signs in to GitHub.

GitHub sign-in uses GitHub's device flow. It prints a web address and a short code. Open https://github.com/login/device in your browser, enter the code and approve access. grit waits until you do, then saves the token with your credential helper. Every request goes straight to github.com.

The token is saved with your credential helper. When no credential.helper is set, grit sets one in your global config first and tells you which:

  • on macOS, osxkeychain (the keychain);
  • on Linux, libsecret when it is installed;
  • on Windows, its built-in one (grit manager), stored as the absolute path of grit.exe followed by manager so that git can run it too;
  • otherwise store, which keeps tokens in plain text in ~/.git-credentials.

To use a different one, set it yourself with grit config before signing in:

$ grit config --global credential.helper libsecret

The helper is shared with Git and asked the same way: grit sends it the protocol and host (protocol=https, host=github.com), so one stored entry covers every repository on that host, and entries Git already saved, such as lines in ~/.git-credentials, work as they are. Set credential.useHttpPath to keep a separate entry per repository; the helper then also gets the repository path (path=owner/repo.git).

grit auth logout removes the saved token for the same default host from your credential helper: GitButler Code's, or GitHub's inside a repository whose origin is on github.com.

grit signs in with its own GitHub OAuth app. To use a different one, set its client id in the GRIT_GITHUB_CLIENT_ID environment variable or the grit.githubClientId setting.

Signing in to a grit serve host

grit auth <url> signs in to a server run by grit serve instead. The URL can be the server's address or any repository URL on it, such as http://git.example.com:8080/app.git; without a scheme it is taken as https://. A github.com URL signs in to GitHub as above.

It works like the GitHub sign-in. grit prints the server's sign-in page and a short code, and opens the page in your browser when it can. Sign in there with your email address and password (from the server's admin), check that the page shows the same code, and approve. grit then saves a new token with your credential helper for the server's scheme and host, under your email address. After that, grit and git clone, fetch and push to every repository on the host without asking.

To store a token you already have instead, for example one an admin made with grit serve token for a CI job, pass --token: grit checks it with the server before saving it.

grit auth logout <url> removes the token saved for that host.

Any other host, such as GitLab, Gitea or a company server, is not a grit serve host: grit auth <url> says so and points at --username and --token below, without changing your config.

Saving a username and token for any HTTPS host

grit never asks for a password on the terminal, so pushes and fetches don't hang waiting for input. To save the user name and personal access token (or password) a host gave you, pass both:

$ grit auth https://gitlab.com/team/app.git --username ada --token "$GITLAB_TOKEN"
✓ Stored the token for ada on gitlab.com — the next push or fetch uses it.

This works for any http:// or https:// URL, GitHub included. grit saves the pair with your credential helper (setting one up first, as above) under the URL's scheme and host, so it covers every repository on that host, for Git as well. With credential.useHttpPath set, it is saved for that repository's path instead, matching how pushes and fetches look it up, so pass the repository URL; credential.<url>.helper settings for the URL apply too. Nothing is sent to the host at this point: the next push, fetch or clone uses the token, and if the host refuses it, that command fails with kind auth_rejected and the helper drops it, as Git does. Run the same command again with the new token. A token on the command line can end up in your shell history; in CI, an askpass program (see Credentials) avoids that.

Options

Option Description
<url> Sign in to the grit serve host this URL names instead of GitHub (or, with --username, the host to store a token for).
--token <token> Store this access token: alone, for a grit serve host (from grit serve token), checked with the server instead of signing in in the browser; with --username, for any HTTP(S) host. A token on the command line can end up in your shell history.
--username <user> Store --token for this user name on the URL's host, without contacting it. Needs <url> and --token.
logout Remove the saved GitHub token.
logout <url> Remove the token saved for a grit serve host.
--dry-run On logout, report which stored credential would be erased without calling the helper.

JSON output

Schema: v1 · auth.logout v1

Pass --json for stable, scripting-friendly output:

Field Type Meaning
authenticated boolean For sign-in, whether a token was stored.
logged_out boolean For logout, whether a stored token was removed (or would be removed with --dry-run).
host string Host the credential applies to: github.com, or a grit serve host with its port (git.example.com:8080).
user string or omitted For sign-in to a grit serve host, the email address of the user the token belongs to; with --username, that user name. Omitted for GitHub.
verified boolean For sign-in, whether the host confirmed the token. false with --username, which stores the token without contacting the host.
dry_run boolean On logout, true when --dry-run was used.
credential object or omitted With --dry-run, describes the helper entry that would be removed (protocol, host, username; never includes a password).

logged_out is false when no credential helper is configured, since there's nowhere a token could be stored.

Markdown output

Pass --markdown for agent-friendly output.

Schema: v1 · auth.logout v1

Markdown uses headings, bullet lists, and fenced blocks; pipe characters inside table cells are escaped. See the JSON output section for the stable field contract.

For a grit serve host the line names the user: - Signed in to **`git.example.com:8080`** as **`bob@example.com`**. With --username it reads - Stored a token for **`ada`** on **`gitlab.com`** (not verified; the next push or fetch uses it).

Exit status

Code Meaning
0 Success (success).
1 Command failed (failure).
2 Invalid flags or arguments (usage).

See Exit codes for shared rules and structured --json kind values.