---
name: "gt-auth-login"
section: "1"
platform: "linux"
package: "gitea-cli"
version: "1.0.0-1"
release: "Arch Linux 2026-11-07"
platforms: ["linux"]
url: "https://carta.tech/man/gt-auth-login"
---

# gt-auth-login(1)

Log in to a Gitea instance

## NAME

gt-auth-login - Log in to a Gitea instance

## SYNOPSIS

**gt auth login \[flags\]**

## 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.

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.

## OPTIONS

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

**--client-id**=""\
 	OAuth application **ID** registered on the instance (default: the instance's stored ID, then gt's); implies --oauth

**--client-key**=""\
 	Unencrypted PEM private key **file** 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

**--credential-store**="keyring"\
 	Where to keep the token {keyring\|file}

**--header**=\[\]\
 	Send the **"Name: value"** 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)

**-h**, **--help**\[=false\]\
 	help for login

**--insecure**\[=false\]\
 	Skip TLS certificate verification for this instance

**--oauth**\[=false\]\
 	Authorize in a web browser with OAuth

**--scopes**=\[\]\
 	OAuth token **scopes**, such as read:repository (default: write access to everything but administration); implies --oauth

**--ssh-agent-key**=""\
 	Sign requests with the ssh-agent key of **fingerprint**

**--ssh-agent-principal**=""\
 	Sign requests with the ssh-agent certificate of **principal**

**--ssh-key**=""\
 	Sign requests with the SSH private key in **file**

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

## OPTIONS INHERITED FROM PARENT COMMANDS

**--debug**\[=false\]\
 	Log the method, URL, status, and duration of each HTTP request to stderr

**--host**=""\
 	Gitea instance **URL**, including any base path

**--interactive**\[=false\]\
 	Allow prompts with machine output

**--no-input**\[=false\]\
 	Disable prompts and implicit editor/browser interactions

**--sudo**=""\
 	Perform API requests as this **user** (requires an administrator account)

**--user**=""\
 	Account **name** on the selected instance

**-y**, **--yes**\[=false\]\
 	Accept confirmations without prompting

## EXAMPLE

```
$ 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'
```

## SEE ALSO

**[gt-auth(1)](/man/gt-auth/1.md)**