gitea-gt-cli/references/auth.md

auth (gt auth)

Authentication, accounts, git credential setup, and environment variables. gt <cmd> --help is authoritative.

gt keeps accounts in hosts.yml and tokens in the system keyring (or a private file), under ~/.config/gitea-cli/ (GITEA_CLI_CONFIG_DIR overrides). It never reads tea's config. One account per instance is active; --user or GITEA_CLI_USER selects another for a single command.

Commands

gt auth <command>
  login  logout  refresh  setup-git  status  switch  token

login

Without a method flag on a terminal it asks for the instance, login method, token storage and whether git should use gt.

Flag	Meaning
--with-token	Read an access token from stdin (or ask on a terminal)
--oauth	Authorize in a browser; --client-id ID selects the OAuth app
--scopes scopes	OAuth scopes, e.g. read:repository,read:user (implies --oauth)
--credential-store {keyring|file}	Where to keep the token (default keyring)
--insecure	Skip TLS verification for this instance
--header "Name: value"	Send a header with every request (repeatable; $VAR expansion)
--ssh-key file, --ssh-agent-key fp, --ssh-agent-principal p	Sign requests with SSH
--client-cert file, --client-key file	TLS client certificate
-y, --yes	Replace an existing account without confirming

gt auth login
gt auth login --host gitea.com --with-token < token.txt
gt auth login --host gitea.com --oauth --scopes read:repository,read:user
gt auth login --host g.example.com --with-token \
  --header 'CF-Access-Client-Id: $CF_ID' --header 'CF-Access-Client-Secret: $CF_SECRET'

Create a token on the instance under Settings > Applications. The first instance logged in to becomes default_host unless one is set.

status / token / switch / setup-git / logout / refresh

• status [--verify] [--json ...] — accounts per instance, active one, method. Fails with exit 4 when there is no account or the credential is missing/rejected, and 1 when --verify gets no answer; with --json it exits 0 either way, so read credential_available, verified, error. JSON fields: active, credential_available, credential_store, error, expires_at, git_credential_helper, host, method, scopes, user, verified.
• token — print the active token (refreshing an expiring OAuth token). SSH-key accounts have no token.
• switch — change the active account of an instance.
• setup-git [--keep-helpers] [--local] — configure git to ask gt for credentials. Other credential helpers are turned off for the instance unless --keep-helpers; --local configures only the current repository.
• logout, refresh.

gt auth status --verify
gt auth status --host gitea.com --json
curl -H "Authorization: token $(gt auth token)" https://gitea.com/api/v1/user

Environment variables

• GITEA_TOKEN + GITEA_INSTANCE_URL (or GITEA_CLI_HOST): use a token instead of stored credentials. GITEA_TOKEN replaces the active account of its instance for the active account too; it must belong to the account --user/GITEA_CLI_USER names.
• In Gitea Actions, GITEA_TOKEN is enough: gt picks the instance from the job (GITEA_SERVER_URL), like gh on GitHub.
• GITEA_CLI_* prefixed variables mirror global flags and settings; see gt help environment for the full list (config dir, user, repo, editor, pager, color, http timeout, data dir, extensions, ...).
• GITEA_INSTANCE_INSECURE, GITEA_INSTANCE_SSH_HOST: pair with GITEA_TOKEN.

doctor

gt doctor [-R ...] [--json ...] checks the setup commands in this directory use: settings files, the instance and its headers, whether it answers, the account and credential, the repository, and git. Each problem names the command that fixes it; gt doctor fails when a check fails. JSON fields: checks, host, host_source, repo, repo_source, user, user_source.

gt doctor
gt doctor -R gitea.com/gitea/cli
gt doctor --jq '.checks[] | select(.status == "failed")'