mirror of
https://gitea.com/gitea/tea.git
synced 2026-10-26 11:01:25 +01:00
bircni
f03d0fdf54
Every value completed to file names, because no command registered a completion. Values without a completer now complete nothing, and only path flags (--*-file, --input, --attachment, --asset, --file, --ssh-key, --dir, --cwd) and arguments named file or directory complete paths. --json completes the fields of the command, also after a comma. --host, --user, --remote and -R complete from hosts.yml, Git remotes and the instance. enumFlag and enumValues give a flag one list of values that validation (case-insensitive) and completion share, and instance completers for issues, pull requests, labels, milestones, users, branches, tags, releases, organizations, teams, workflows, runs, secrets and variables are ready for commands to attach. They give up after two seconds, never prompt, retry or refresh an OAuth token, and drop values with control characters. tea completion bash now says to use eval "$(tea completion bash)", because bash 3.2 on macOS cannot source <(...), and names the bash-completion package; the zsh help says to run compinit first. The README matches. Signed-off-by: bircni <bircni@icloud.com>
144 lines
6.5 KiB
Markdown
144 lines
6.5 KiB
Markdown
# <img alt='tea logo' src='https://gitea.com/repo-avatars/550-80a3a8c2ab0e2c2d69f296b7f8582485' height="40"/> *T E A*
|
|
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://gitea.com/gitea/tea/releases)
|
|
[](https://discord.gg/Gitea)
|
|
[](https://goreportcard.com/report/gitea.dev/tea) [](https://godoc.org/gitea.dev/tea)
|
|
|
|
|
|
## The official CLI for Gitea
|
|
|
|
Tea manages repositories, issues, pull requests, releases, and other Gitea resources
|
|
with explicit commands suitable for local development and CI.
|
|
|
|
```sh
|
|
tea auth login --host https://gitea.example.org --with-token < token-file
|
|
tea issue list --repo owner/repository
|
|
tea pr view 123 --repo owner/repository --json
|
|
tea alias set bugs 'issue list --label bug'
|
|
tea help
|
|
```
|
|
|
|
tea 1.0 is a breaking release: it requires Gitea 28 or newer, commands, flags and
|
|
output formats changed, it uses separate `config.yml` and `hosts.yml` files, and it
|
|
requires fresh authentication.
|
|
Existing combined configuration files are left untouched; archive the old file or
|
|
choose an isolated `TEA_CONFIG_DIR` before setup. See
|
|
[Migrating to tea 1.0](docs/migration-1.0.md) for the old-to-new mapping.
|
|
Run `tea --help` or `tea <command> --help` for supported commands and flags; the
|
|
full reference, man pages, and shell completions ship in each release's docs archive.
|
|
Credentials use the operating-system keyring by default; explicitly
|
|
select `--credential-store file` when private file storage is needed. For CI,
|
|
supply `GITEA_TOKEN` and its instance through `TEA_HOST` or `GITEA_INSTANCE_URL`;
|
|
environment credentials are never persisted.
|
|
|
|
## Installation
|
|
|
|
There are different ways to get `tea`:
|
|
|
|
1. Install via your system package manager:
|
|
- macOS via `brew` (official):
|
|
```sh
|
|
brew install tea
|
|
```
|
|
- arch linux ([tea](https://archlinux.org/packages/extra/x86_64/tea/), thirdparty)
|
|
- alpine linux ([tea](https://pkgs.alpinelinux.org/packages?name=tea&branch=edge), thirdparty)
|
|
- Windows via `MSYS2` ([tea](https://packages.msys2.org/base/mingw-w64-tea), thirdparty)
|
|
|
|
2. Use the prebuilt binaries from [dl.gitea.com](https://dl.gitea.com/tea/)
|
|
|
|
3. Install from source: [see *Compilation*](#compilation)
|
|
|
|
4. Docker: [Tea at docker hub](https://hub.docker.com/r/gitea/tea)
|
|
|
|
### Log in to Gitea from tea
|
|
|
|
Gitea can use many different authentication schemes, and not every authentication method will work with every Gitea deployment. When you are a Gitea instance administrator you can tweak your settings to fit your use case. For the method that is most likely to work with any Gitea deployment use the following steps:
|
|
|
|
1. Open your Gitea instance in a web browser
|
|
|
|
2. Log in to Gitea in your web browser. Any MFA, IDP, or whatever else should be available this way.
|
|
|
|
3. In your "user settings", generate an application token with at least **user read** permissions. If you want to do anything useful with the token add additional permissions/scopes.
|
|
|
|
4. Save the token in a private file and run `tea auth login --host https://your-instance --with-token < token-file`. Credentials use the operating-system keyring by default.
|
|
|
|
You should now be logged in to your gitea instance from tea.
|
|
|
|
Alternatively, `tea auth login --host https://your-instance --oauth` authorizes tea in your browser. OAuth may not be available on all Gitea deployments, and needs a browser on the machine running tea.
|
|
|
|
### Shell completion
|
|
|
|
If you installed from source or the package does not provide the completions with it you can add them yourself with `tea completion <shell>` command. Completion offers commands, flags, flag values such as `--state` and `--json` fields, and values from your instance such as repositories. Add the line for your shell to its startup file:
|
|
|
|
```shell
|
|
# ~/.bashrc (on macOS, ~/.bash_profile)
|
|
eval "$(tea completion bash)"
|
|
|
|
# ~/.zshrc, after compinit
|
|
autoload -U compinit && compinit
|
|
source <(tea completion zsh)
|
|
|
|
# fish
|
|
tea completion fish > ~/.config/fish/completions/tea.fish
|
|
|
|
# PowerShell profile
|
|
tea completion powershell | Out-String | Invoke-Expression
|
|
```
|
|
|
|
The bash script needs the bash-completion package. On macOS, install `bash-completion` with Homebrew for the system bash 3.2 (or `bash-completion@2` for a Homebrew bash 4.2+), and use `eval` as above: bash 3.2 cannot `source <(...)`. Without `compinit`, zsh reports `command not found: compdef`. `tea completion <shell> --help` shows these steps and how to install the script system-wide.
|
|
|
|
### Man Page
|
|
|
|
The hidden command `tea man` can be used to generate the `tea` man page.
|
|
|
|
```shell
|
|
# for bash or zsh
|
|
man <(tea man)
|
|
|
|
# for fish
|
|
man (tea man | psub)
|
|
|
|
# write man page to a file
|
|
tea man --output-file ./tea.man
|
|
```
|
|
|
|
## Compilation
|
|
|
|
Make sure you have a current Go version installed (1.27 or newer).
|
|
|
|
- To compile the source yourself with the recommended flags & tags:
|
|
```sh
|
|
git clone https://gitea.com/gitea/tea.git # or: tea repo clone https://gitea.com/gitea/tea ;)
|
|
cd tea
|
|
make
|
|
```
|
|
Note that GNU Make (gmake on OpenBSD) is required.
|
|
If you want to install the compiled program you have to execute the following command:
|
|
```sh
|
|
make install
|
|
```
|
|
This installs the binary into the "bin" folder inside of your GOPATH folder (`go env GOPATH`). It is possible that this folder isn't in your PATH Environment Variable.
|
|
|
|
- For a quick installation without `git` & `make`, set $version and exec:
|
|
```sh
|
|
go install gitea.dev/tea@${version}
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Fork -> Patch -> Push -> Pull Request
|
|
|
|
- `make test` run unit tests
|
|
- `make vet` run checks (check the order of imports; preventing failure on CI pipeline beforehand)
|
|
- `make build` builds the production CLI
|
|
- `make docs` regenerates references, man pages, and shell completions in `docs/generated` (not committed; built on release)
|
|
- ... (for other development tasks, check the `Makefile`)
|
|
|
|
**Please** read the [CONTRIBUTING](CONTRIBUTING.md) documentation, it will tell you about internal structures and concepts.
|
|
|
|
## License
|
|
|
|
This project is under the MIT License. See the [LICENSE](LICENSE) file for the
|
|
full license text.
|