mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-04 17:19:52 +00:00
Add documentation for gt, the Gitea CLI (#603)
Adds a CLI product for gt (https://gitea.com/gitea/cli), set up like the runner, with short guides for installation, logging in, CI and scripting. Each command's details stay in gt <command> --help. Until the first release, the docs are served at /cli/; make cut-version PRODUCT=cli VERSION=0.1 adds the release series. Closes https://gitea.com/gitea/cli/issues/16 <!-- cloudflare-preview --> Preview: https://pr-603.docs-gitea-com.pages.dev --------- Co-authored-by: silverwind <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/603 Reviewed-by: Lunny Xiao <[email protected]> Reviewed-by: silverwind <[email protected]>
This commit is contained in:
bircniandsilverwind committed
1 parent
9699ec2c87
commit
09bb4cabcf
20 files changed
+315
-45
No files matched your search
@@ -0,0 +1,55 @@
|
||||
---
|
||||
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.
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Using gt in CI
|
||||
|
||||
Give gt a token and an instance through the environment, and turn prompts off:
|
||||
|
||||
| Variable | Description |
|
||||
| --- | --- |
|
||||
| `GITEA_TOKEN` | Access token; gt never stores it |
|
||||
| `GITEA_CLI_HOST` or `GITEA_INSTANCE_URL` | URL of the instance |
|
||||
| `GITEA_CLI_REPO` | Repository, like `--repo` |
|
||||
|
||||
`--no-input` makes a command fail instead of prompting, and `--yes` confirms changes in
|
||||
advance.
|
||||
|
||||
## Gitea Actions
|
||||
|
||||
Gitea does not allow secret names that start with `GITEA_`, so store the token as, for
|
||||
example, `GT_TOKEN`:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
staging:
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
GITEA_TOKEN: ${{ secrets.GT_TOKEN }}
|
||||
GITEA_CLI_HOST: ${{ gitea.server_url }}
|
||||
GITEA_CLI_REPO: ${{ gitea.repository }}
|
||||
steps:
|
||||
- run: curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
|
||||
- run: gt workflow run deploy.yml --ref main --field env=staging --no-input
|
||||
```
|
||||
|
||||
`gt run watch` and `gt pr checks --watch` wait for runs and checks and fail when one fails.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
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 and the other resources of a
|
||||
Gitea instance, from a terminal or a script.
|
||||
|
||||
:::info Development version
|
||||
These pages describe builds from the `main` branch, published as `nightly` binaries and images.
|
||||
:::
|
||||
|
||||
gt needs Gitea 28 or later, and Git for the commands that clone, check out or push.
|
||||
|
||||
## Getting started
|
||||
|
||||
1. [Install gt](installation.md).
|
||||
2. [Log in](authentication.md):
|
||||
|
||||
```bash
|
||||
gt auth login
|
||||
```
|
||||
|
||||
3. Run commands in a clone of a repository on that instance, or select one with `--repo`:
|
||||
|
||||
```bash
|
||||
gt issue list --label bug
|
||||
gt pr checkout 13
|
||||
gt issue view 42 --repo gitea.com/gitea/cli
|
||||
```
|
||||
|
||||
`gt doctor` checks your setup and suggests a fix for each problem it finds.
|
||||
|
||||
`gt <command> --help` lists the flags of a command, and `gt help environment` the global
|
||||
flags and environment variables.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Installation
|
||||
|
||||
gt is a single binary for Linux, macOS, Windows and FreeBSD.
|
||||
|
||||
## Install script
|
||||
|
||||
The install script downloads gt from [dl.gitea.com](https://dl.gitea.com/gitea-cli/),
|
||||
verifies its checksum and installs it.
|
||||
|
||||
```bash
|
||||
# Linux, macOS, FreeBSD
|
||||
curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
|
||||
```
|
||||
|
||||
```powershell
|
||||
# Windows
|
||||
irm https://gitea.com/gitea/cli/raw/branch/main/scripts/install.ps1 | iex
|
||||
```
|
||||
|
||||
Set `GITEA_CLI_VERSION` to install a specific version, or `nightly` for the latest build
|
||||
of `main`.
|
||||
|
||||
## Other ways
|
||||
|
||||
- **Binaries:** download them from [dl.gitea.com/gitea-cli](https://dl.gitea.com/gitea-cli/).
|
||||
- **Docker:** the [`gitea/gitea-cli`](https://hub.docker.com/r/gitea/gitea-cli) image runs
|
||||
`gt` as its entry point.
|
||||
- **Go:** `go install gitea.dev/cli/cmd/gt@latest`
|
||||
|
||||
## Shell completion and man pages
|
||||
|
||||
`gt completion <shell>` prints the completion script for bash, zsh, fish or PowerShell;
|
||||
`gt completion <shell> --help` shows how to load it. `gt man` prints the manual.
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Output and scripting
|
||||
|
||||
Scripts should read JSON: the text output is meant for people and may change.
|
||||
|
||||
```bash
|
||||
gt pr view 123 --json number,title,state
|
||||
gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
|
||||
```
|
||||
|
||||
`--json` prints all fields or the ones you list; the **JSON FIELDS** section of a command's
|
||||
`--help` names them. `--jq` filters the result without needing jq installed. Piped lists
|
||||
print as tab-separated values.
|
||||
|
||||
gt exits with 0 on success, 1 when a command fails, 2 on a usage error and 4 when
|
||||
authentication is missing or rejected; `gt help exit-codes` lists all codes.
|
||||
|
||||
`gt api` calls any API endpoint with gt's login, and `gt alias set` defines shortcuts for
|
||||
commands you use often.
|
||||
Reference in new issue
Block a user