docs/cli-docs/index.md

sidebar_position, slug

sidebar_position	slug
1	/

Gitea CLI

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

2. Log in to your Gitea instance:

   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:

   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:

   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. 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 and Output and scripting.