README.md

@@ -2,14 +2,71 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Release](https://raster.shields.io/badge/dynamic/json.svg?label=release&url=https://gitea.com/api/v1/repos/gitea/tea/releases&query=$[0].tag_name)](https://gitea.com/gitea/tea/releases) [![Build Status](https://drone.gitea.com/api/badges/gitea/tea/status.svg)](https://drone.gitea.com/gitea/tea) [![Join the chat at https://img.shields.io/discord/322538954119184384.svg](https://img.shields.io/discord/322538954119184384.svg)](https://discord.gg/Gitea) [![Go Report Card](https://goreportcard.com/badge/code.gitea.io/tea)](https://goreportcard.com/report/code.gitea.io/tea) [![GoDoc](https://godoc.org/code.gitea.io/tea?status.svg)](https://godoc.org/code.gitea.io/tea)
 
-## The official CLI interface for gitea
+### the official CLI interface for gitea
+```
+   tea - command line tool to interact with Gitea
+   version 0.6.0+9-g75d415b
 
-Tea is a command line tool for interacting on one or more Gitea instances.
-It uses [code.gitea.io/sdk](https://code.gitea.io/sdk) and interacts with the Gitea API
+ USAGE
+   tea command [subcommand] [command options] [arguments...]
 
-![demo gif](https://dl.gitea.io/screenshots/tea_demo.gif)
+ DESCRIPTION
+   tea is a productivity helper for Gitea.  It can be used to manage most entities on one
+   or multiple Gitea instances, and also provides local helpers like 'tea pull checkout'.
+   tea makes use of context provided by the repository in $PWD if available, but is still
+   usable independently of $PWD. Configuration is persisted in $XDG_CONFIG_HOME/tea.
 
-For a feature comparison with other git forge CLIs see [here](./FEATURE-COMPARISON.md).
+ COMMANDS
+   help, h  Shows a list of commands or help for one command
+   ENTITIES:
+     issues, issue                     List, create and update issues
+     pulls, pull, pr                   List, create, checkout and clean pull requests
+     labels, label                     Manage issue labels
+     milestones, milestone, ms         List and create milestones
+     releases, release                 Manage releases
+     times, time                       Operate on tracked times of a repository's issues & pulls
+     organizations, organization, org  List, create, delete organizations
+     repos, repo                       Show repository details
+   HELPERS:
+     open                                Open something of the repository on web browser
+     notifications, notification, notif  Show notifications
+   SETUP:
+     logins, login  Log in to a Gitea server
+     logout         Log out from a Gitea server
+
+ OPTIONS
+   --help, -h     show help (default: false)
+   --version, -v  print the version (default: false)
+
+ EXAMPLES
+   tea login add                       # add a login once to get started
+
+   tea pulls                           # list open pulls for the repo in $PWD
+   tea pulls --repo $HOME/foo          # list open pulls for the repo in $HOME/foo
+   tea pulls --remote upstream         # list open pulls for the repo pointed at by
+                                       # your local "upstream" git remote
+   # list open pulls for any gitea repo at the given login instance
+   tea pulls --repo gitea/tea --login gitea.com
+
+   tea milestone issues 0.7.0          # view open issues for milestone '0.7.0'
+   tea issue 189                       # view contents of issue 189
+   tea open 189                        # open web ui for issue 189
+   tea open milestones                 # open web ui for milestones
+
+   # send gitea desktop notifications every 5 minutes (bash + libnotify)
+   while :; do tea notifications --all -o simple | xargs -i notify-send {}; sleep 300; done
+
+ ABOUT
+   Written & maintained by The Gitea Authors.
+   If you find a bug or want to contribute, we'll welcome you at https://gitea.com/gitea/tea.
+   More info about Gitea itself on https://gitea.io.
+```
+
+
+- [Watch a short demo GIF](https://dl.gitea.io/screenshots/tea_demo.gif)
+- [Compare features with other git forge CLIs](./FEATURE-COMPARISON.md)
+
+Tea uses [code.gitea.io/sdk](https://code.gitea.io/sdk) and interacts with the Gitea API.
 
 ## Installation
 
@@ -31,36 +88,6 @@ brew install tea
 
 Distribution packages exist for: **alpinelinux ([tea](https://pkgs.alpinelinux.org/packages?name=tea&branch=edge))** and **archlinux ([gitea-tea](https://aur.archlinux.org/packages/gitea-tea))**
 
-## Usage
-
-First of all, you have to create a token on your `personal settings -> application` page of your gitea instance.
-Use this token to login with `tea`:
-
-```sh
-tea login add --name=try --url=https://try.gitea.io --token=xxxxxx
-```
-
-Now you can use the following `tea` subcommands.
-Detailed usage information is available via `tea <command> --help`.
-
-```none
-login            Log in to a Gitea server
-logout           Log out from a Gitea server
-issues           List, create and update issues
-pulls            List, create, checkout and clean pull requests
-releases         List, create, update and delete releases
-repos            Operate with repositories
-labels           Manage issue labels
-times            Operate on tracked times of a repositorys issues and pulls
-open             Open something of the repository on web browser
-notifications    Show notifications
-milestones       List and create milestones
-organizations    List, create, delete organizations
-help, h          Shows a list of commands or help for one command
-```
-
-To fetch issues from different repos, use the `--remote` flag (when inside a gitea repository directory) or `--login` & `--repo` flags.
-
 ## Compilation
 
 Make sure you have installed a current go version.