---
sidebar_position: 1
slug: /
---

# Gitea CLI

[gt](https://gitea.com/gitea/cli) is the official command line client for Gitea.
It works with repositories, issues, pull requests, releases, Actions workflows and runs,
packages, and the other resources of a Gitea instance, from a terminal or from a script.

:::info Development version
These pages describe builds from the `main` branch of gitea/cli, published as `nightly`
binaries and images.
:::

## Requirements

- Gitea 28 or later. gt does not support older instances.
- Git on the `PATH`, for the commands that clone, check out or push, such as
  `gt repo clone` and `gt pr checkout`.

## Getting started

1. [Install gt](installation.md).
2. [Log in](authentication.md) to your Gitea instance:

   ```bash
   gt auth login
   ```

3. Run commands from a clone of a repository on that instance. gt finds the repository
   and the instance from the Git remotes:

   ```bash
   gt issue list --label bug
   gt pr checkout 13
   gt pr checks --watch
   ```

   Outside a clone, select the repository with `--repo` (`-R`), as `OWNER/REPO` or as a URL:

   ```bash
   gt issue view 42 --repo gitea.com/gitea/cli
   ```

`gt doctor` checks the setup that commands in the current directory use: the settings
files, the instance, the account and its credential, the repository, and Git. Each
problem it reports comes with the command that fixes it.

## Commands

Commands are a noun followed by a verb, such as `gt issue list` or `gt pr create`.
Every command has a `--help` page, which is also part of the
[command reference](reference/index.md). Besides the commands, gt has three help topics:

- `gt help environment`: global flags, environment variables, and how gt selects the
  instance and the repository
- `gt help formatting`: JSON output with `--json` and `--jq`
- `gt help exit-codes`: the exit codes

For scripts and CI, read [Using gt in CI](ci.md) and [Output and scripting](scripting.md).