93 lines
3.9 KiB
Markdown
93 lines
3.9 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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 prompt) |
|
|
| `--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 |
|
|
|
|
```bash
|
|
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; with `--json` it exits 0 and you 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` — log out of an account.
|
|
- `refresh` — refresh an OAuth token.
|
|
|
|
```bash
|
|
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.
|
|
- `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, ...).
|
|
- `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`.
|
|
|
|
```bash
|
|
gt doctor
|
|
gt doctor -R gitea.com/gitea/cli
|
|
gt doctor --jq '.checks[] | select(.status == "failed")'
|
|
```
|