.nh
.TH "GT-AUTH-LOGIN" "1" "Nov 2026" "gitea-cli" "gitea-cli Manual"

.SH NAME
gt-auth-login - Log in to a Gitea instance


.SH SYNOPSIS
\fBgt auth login [flags]\fP


.SH DESCRIPTION
Log in to a Gitea instance. On a terminal without a method flag, gt asks for the instance,
how to log in, where to keep the token and whether git should use gt for the instance.

.PP
Create a token on the instance under Settings > Applications. Logging in to an account
that gt already has replaces its stored credential after a confirmation (or with --yes).
The first instance logged in to becomes default_host, unless one is set.


.SH OPTIONS
\fB--client-cert\fP=""
	Present the PEM TLS client certificate in \fBfile\fR to an instance that requires one; convert a PKCS#12 file with: openssl pkcs12 -in cert.p12 -clcerts -nokeys -out cert.pem

.PP
\fB--client-id\fP=""
	OAuth application \fBID\fR registered on the instance (default: the instance's stored ID, then gt's); implies --oauth

.PP
\fB--client-key\fP=""
	Unencrypted PEM private key \fBfile\fR of --client-cert (default: the key in the --client-cert file); convert a PKCS#12 file with: openssl pkcs12 -in cert.p12 -nocerts -nodes -out key.pem

.PP
\fB--credential-store\fP="keyring"
	Where to keep the token {keyring|file}

.PP
\fB--header\fP=[]
	Send the \fB"Name: value"\fR header with every request to this instance, such as an access proxy needs; a value of $NAME or ${NAME} is read from that environment variable (repeatable)

.PP
\fB-h\fP, \fB--help\fP[=false]
	help for login

.PP
\fB--insecure\fP[=false]
	Skip TLS certificate verification for this instance

.PP
\fB--oauth\fP[=false]
	Authorize in a web browser with OAuth

.PP
\fB--scopes\fP=[]
	OAuth token \fBscopes\fR, such as read:repository (default: write access to everything but administration); implies --oauth

.PP
\fB--ssh-agent-key\fP=""
	Sign requests with the ssh-agent key of \fBfingerprint\fR

.PP
\fB--ssh-agent-principal\fP=""
	Sign requests with the ssh-agent certificate of \fBprincipal\fR

.PP
\fB--ssh-key\fP=""
	Sign requests with the SSH private key in \fBfile\fR

.PP
\fB--with-token\fP[=false]
	Read an access token from stdin, or ask for it on a terminal


.SH OPTIONS INHERITED FROM PARENT COMMANDS
\fB--debug\fP[=false]
	Log the method, URL, status, and duration of each HTTP request to stderr

.PP
\fB--host\fP=""
	Gitea instance \fBURL\fR, including any base path

.PP
\fB--interactive\fP[=false]
	Allow prompts with machine output

.PP
\fB--no-input\fP[=false]
	Disable prompts and implicit editor/browser interactions

.PP
\fB--sudo\fP=""
	Perform API requests as this \fBuser\fR (requires an administrator account)

.PP
\fB--user\fP=""
	Account \fBname\fR on the selected instance

.PP
\fB-y\fP, \fB--yes\fP[=false]
	Accept confirmations without prompting


.SH EXAMPLE
.EX
$ 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 gitea.example.com --with-token --header 'CF-Access-Client-Id: $CF_ID' --header 'CF-Access-Client-Secret: $CF_SECRET'
.EE


.SH SEE ALSO
\fBgt-auth(1)\fP