---
sidebar_position: 3
---

# Logging in

On a terminal, `gt auth login` asks for the instance and how to log in. gt never asks for
your password.

## OAuth in a browser

```bash
gt auth login --host https://gitea.example.com --oauth
```

gt opens the instance's authorization page, so single sign-on and two-factor
authentication work as on the web. The browser has to run on the same machine as gt.
`--scopes` limits the token to fewer [scopes](/development/oauth2-provider#scopes); gt
refreshes OAuth tokens on its own.

## Access token

Create a token under **Settings > Applications** on the instance and pass it on stdin:

```bash
gt auth login --host https://gitea.example.com --with-token < token.txt
```

The token needs `read:user`, and the scopes of what you do with gt, such as
`write:repository` and `write:issue` for working on pull requests.

## SSH key

gt can sign its requests with an SSH key registered for your account instead of using a
token:

```bash
gt auth login --host https://gitea.example.com --ssh-key ~/.ssh/id_ed25519
```

## Accounts

Tokens go to the system keyring, or with `--credential-store file` to gt's configuration
directory on machines without one. Run `gt auth login` once per instance and account.
gt picks the instance from the repository's remote or `--host`, and the account with
`gt auth switch` or `--user`. `gt auth status` lists your accounts and `gt auth logout`
removes one.

For instances behind an access proxy, `--header` and `--client-cert` add headers and a
client certificate.

## Git over HTTPS

`gt auth setup-git` lets `git push` and `git fetch` over HTTPS use gt's login. gt's own
clone and checkout commands need no setup.