Man pages

[ottok]

Feature Request

The commands in TiUP do not currently have any man pages. Typically all commands in a Linux/Unix system have man pages, which can be browsed on the command-line e.g. man tiup or via websites such as https://dyn.manpages.debian.org/ or https://manpages.ubuntu.com/.

This feature request was motivated by Lintian nagging about https://lintian.debian.org/tags/no-manual-page.html in Debian:

W: tiup: no-manual-page [usr/bin/client]
N: 
N:   Each binary in /usr/bin, /usr/sbin, /bin, /sbin or /usr/games should have
N:   a manual page
N:   
N:   Note that though the man program has the capability to check for several
N:   program names in the NAMES section, each of these programs should have its
N:   own manual page (a symbolic link to the appropriate manual page is
N:   sufficient) because other manual page viewers such as xman or tkman don't
N:   support this.
N:   
N:   If the name of the manual page differs from the binary by case, man may be
N:   able to find it anyway; however, it is still best practice to match the
N:   exact capitalization of the executable in the manual page.
N:   
N:   If the manual pages are provided by another package on which this package
N:   depends, Lintian may not be able to determine that manual pages are
N:   available. In this case, after confirming that all binaries do have manual
N:   pages after this package and its dependencies are installed, please add a
N:   Lintian override.
N: 
N:   Please refer to Manual pages (Section 12.1) in the Debian Policy Manual
N:   for details.
N: 
N:   Visibility: warning
N:   Show-Always: no
N:   Check: documentation/manual
N:   Renamed from: binary-without-manpage
N: 
N:
W: tiup: no-manual-page [usr/bin/cluster]
N:
W: tiup: no-manual-page [usr/bin/ctl]
N:
W: tiup: no-manual-page [usr/bin/dm]
N:
W: tiup: no-manual-page [usr/bin/package]
N:
W: tiup: no-manual-page [usr/bin/playground]
N:
W: tiup: no-manual-page [usr/bin/server]
N:
W: tiup: no-manual-page [usr/bin/tiup]

Related: #2508 #2507

[rpaik]

Hi @ottok,

One option I discussed with @dveeden was to create a high-level static content with link(s) to TiUP docs pages.

[ottok]

That would work

…

Message ID: ***@***.***>

[dveeden]

Having a manpage for tiup would be good. And also for tiup-playground (used as tiup playground, somewhat similar to the git-commit manpage for git commit).

The output shows usr/bin/playground, while I would expect tiup-playground. And that binary should be called by tiup and not directly by users, so it should probably not bin in usr/bin, right?

[dveeden]

.TH TIUP 1 "April 2025" "TiUP v8.4" "User Commands"
.SH NAME
tiup \- A package manager for the TiDB ecosystem

.SH SYNOPSIS
.B tiup
[\fIflags\fR] <\fIcommand\fR> [\fIargs...\fR]
.br
.B tiup
[\fIflags\fR] <\fIcomponent\fR> [\fIargs...\fR]

.SH DESCRIPTION
TiUP is a command-line tool that serves as the package manager for the TiDB ecosystem. It manages components such as TiDB, PD, and TiKV, and supports various commands for installation, updating, and management of these components. TiUP also facilitates the management of TiDB clusters and TiDB Data Migration (DM) clusters.

.SH OPTIONS
.TP
.B \-\-binary
Prints the path of the specified binary file. If no version is specified, the latest stable version installed is used. This option is only applicable in the format \fBtiup [flags] <component> [args...]\fR.
.TP
.B \-\-binpath
Specifies the path of the component to be executed, allowing the use of a custom binary file path instead of the default TiUP mirror.
.TP
.B \-T, \-\-tag
Specifies a tag for the component to be started, allowing TiUP to allocate a fixed directory for disk storage during execution.
.TP
.B \-v, \-\-version
Prints the version of TiUP.
.TP
.B \-\-help
Displays help information for TiUP commands and components.

.SH EXAMPLES
.TP
To install a specific version of a component:
.B
tiup install <component>[:version]
.TP
To update all installed components to the latest version:
.B
tiup update \-\-all
.TP
To start a TiDB cluster locally using the playground component:
.B
tiup playground
.TP
To list the available TiDB components or versions:
.B
tiup list

.SH SEE ALSO
For more detailed information, visit the official documentation at:
https://docs.pingcap.com/tidb/v8.4/tiup-overview
https://docs.pingcap.com/tidb/v8.4/tiup-reference

https://tidb.ai/c/01966405-45a0-72f9-8ded-07bb1573ffa7

[ottok]

Looks good to me!

[ottok]

In xo/usql#521 I submitted a man page for usql that would be included in the upstream repository directory man. Could the same pattern apply here, could tiup carry manpage stubs in man/ and the https://github.com/pingcap/tiup/blob/master/install.sh script install them on target system at /usr/local/share/man/man1 or similar?

[ottok]

Output of commands currently:

/usr/bin/client --help
Connect a TiDB cluster in your local host

Usage:
  tiup client [flags]

Flags:
  -h, --help   help for tiup

/usr/bin/cluster --help
Deploy a TiDB cluster for production

Usage:
  cluster [command]

Available Commands:
  check       Perform preflight checks for the cluster.
  deploy      Deploy a cluster for production
  start       Start a TiDB cluster
  stop        Stop a TiDB cluster
  restart     Restart a TiDB cluster
  scale-in    Scale in a TiDB cluster
  scale-out   Scale out a TiDB cluster
  destroy     Destroy a specified cluster
  clean       (EXPERIMENTAL) Cleanup a specified cluster
  upgrade     Upgrade a specified TiDB cluster
  display     Display information of a TiDB cluster
  prune       Destroy and remove instances that is in tombstone state
  list        List all clusters
  audit       Show audit log of cluster operation
  import      Import an exist TiDB cluster from TiDB-Ansible
  edit-config Edit TiDB cluster config
  show-config Show TiDB cluster config
  reload      Reload a TiDB cluster's config and restart if needed
  patch       Replace the remote package with a specified package and restart the service
  rename      Rename the cluster
  enable      Enable a TiDB cluster automatically at boot
  disable     Disable automatic enabling of TiDB clusters at boot
  replay      Replay previous operation and skip successed steps
  template    Print topology template
  tls         Enable/Disable TLS between TiDB components
  meta        backup/restore meta information
  rotatessh   rotate ssh keys on all nodes
  help        Help about any command
  completion  Generate the autocompletion script for the specified shell

Flags:
  -c, --concurrency int     max number of parallel tasks allowed (default 5)
      --format string       (EXPERIMENTAL) The format of output, available values are [default, json] (default "default")
  -h, --help                help for cluster
      --ssh string          (EXPERIMENTAL) The executor type: 'builtin', 'system', 'none'.
      --ssh-timeout uint    Timeout in seconds to connect host via SSH, ignored for operations that don't need an SSH connection. (default 5)
  -v, --version             version for cluster
      --wait-timeout uint   Timeout in seconds to wait for an operation to complete, ignored for operations that don't fit. (default 120)
  -y, --yes                 Skip all confirmations and assumes 'yes'

Use "cluster help [command]" for more information about a command.

/usr/bin/ctl --help

(no output)

/usr/bin/dm --help
EXPERIMENTAL: This is an experimental feature, things may or may not work,
please backup your data before process.

Usage:
  dm [command]

Available Commands:
  deploy      Deploy a DM cluster for production
  start       Start a DM cluster
  stop        Stop a DM cluster
  restart     Restart a DM cluster
  list        List all clusters
  destroy     Destroy a specified DM cluster
  audit       Show audit log of cluster operation
  edit-config Edit DM cluster config
  display     Display information of a DM cluster
  prune       Clear etcd info 
  reload      Reload a DM cluster's config and restart if needed
  upgrade     Upgrade a specified DM cluster
  patch       Replace the remote package with a specified package and restart the service
  scale-out   Scale out a DM cluster
  scale-in    Scale in a DM cluster
  import      Import an exist DM 1.0 cluster from dm-ansible and re-deploy 2.0 version
  enable      Enable a DM cluster automatically at boot
  disable     Disable automatic enabling of DM clusters at boot
  replay      Replay previous operation and skip successed steps
  template    Print topology template
  meta        backup/restore meta information
  rotatessh   rotate ssh keys on all nodes
  help        Help about any command
  completion  Generate the autocompletion script for the specified shell

Flags:
  -c, --concurrency int     max number of parallel tasks allowed (default 5)
      --format string       (EXPERIMENTAL) The format of output, available values are [default, json] (default "default")
  -h, --help                help for dm
      --ssh string          The executor type: 'builtin', 'system', 'none'
      --ssh-timeout uint    Timeout in seconds to connect host via SSH, ignored for operations that don't need an SSH connection. (default 5)
  -v, --version             version for dm
      --wait-timeout uint   Timeout in seconds to wait for an operation to complete, ignored for operations that don't fit. (default 120)
  -y, --yes                 Skip all confirmations and assumes 'yes'

Use "dm help [command]" for more information about a command.

/usr/bin/package --help
Package a tiup component and generate package directory

Usage:
  tiup package target [flags]

Flags:
  -C, -- string          Change directory before compress
      --arch string      Target ARCH of the package (default "amd64")
      --desc string      (deprecated) Description of the package
      --entry string     (deprecated) Entry point of the package
  -h, --help             help for tiup
      --hide tiup list   (deprecated) Don't show the component in tiup list
      --name string      Name of the package (required)
      --os string        Target OS of the package (default "linux")
      --release string   Version of the package (required)
      --standalone       (deprecated) Can the component run standalone

/usr/bin/playground --help
Bootstrap a TiDB cluster in your local host, the latest release version will be chosen
if you don't specified a version.

Examples:
  $ tiup playground nightly                         # Start a TiDB nightly version local cluster
  $ tiup playground v5.0.1 --db 3 --pd 3 --kv 3     # Start a local cluster with 10 nodes
  $ tiup playground nightly --without-monitor       # Start a local cluster and disable monitor system
  $ tiup playground --pd.config ~/config/pd.toml    # Start a local cluster with specified configuration file
  $ tiup playground --db.binpath /xx/tidb-server    # Start a local cluster with component binary path
  $ tiup playground --tag xx                           # Start a local cluster with data dir named 'xx' and uncleaned after exit
  $ tiup playground --mode tikv-slim                # Start a local tikv only cluster (No TiDB or TiFlash Available)
  $ tiup playground --mode tikv-slim --kv 3 --pd 3  # Start a local tikv only cluster with 6 nodes

Usage:
  tiup playground [version] [flags]
  tiup [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  display     
  help        Help about any command
  scale-in    
  scale-out   

Flags:
      --cse.access_key string            Object store access key for --mode=tidb-cse or --mode=tiflash-disagg (default "minioadmin")
      --cse.bucket string                Object store bucket for --mode=tidb-cse or --mode=tiflash-disagg (default "tiflash")
      --cse.s3_endpoint string           Object store URL for --mode=tidb-cse or --mode=tiflash-disagg (default "http://127.0.0.1:9000")
      --cse.secret_key string            Object store secret key for --mode=tidb-cse or --mode=tiflash-disagg (default "minioadmin")
      --db int                           TiDB instance number
      --db.binpath string                TiDB instance binary path
      --db.config string                 TiDB instance configuration file
      --db.host host                     Playground TiDB host. If not provided, TiDB will still use host flag as its host
      --db.port int                      Playground TiDB port. If not provided, TiDB will use 4000 as its port. Or 6000 if TiProxy is enabled.
      --db.timeout int                   TiDB max wait time in seconds for starting, 0 means no limit (default 60)
      --dm-master int                    DM-master instance number
      --dm-master.binpath string         DM-master instance binary path
      --dm-master.config string          DM-master instance configuration file
      --dm-master.host string            DM-master instance host
      --dm-master.port int               DM-master instance port (default 8261)
      --dm-worker int                    DM-worker instance number
      --dm-worker.binpath string         DM-worker instance binary path
      --dm-worker.config string          DM-worker instance configuration file
      --dm-worker.host string            DM-worker instance host
      --dm-worker.port int               DM-worker instance port (default 8262)
      --drainer int                      Drainer instance number
      --drainer.binpath string           Drainer instance binary path
      --drainer.config string            Drainer instance configuration file
      --grafana.port int                 grafana port. If not provided, grafana will use 3000 as its port. (default 3000)
  -h, --help                             help for tiup
      --host string                      Playground cluster host (default "127.0.0.1")
      --kv int                           TiKV instance number
      --kv.binpath string                TiKV instance binary path
      --kv.config string                 TiKV instance configuration file
      --kv.host host                     Playground TiKV host. If not provided, TiKV will still use host flag as its host
      --kv.port int                      Playground TiKV port. If not provided, TiKV will use 20160 as its port
      --kvcdc int                        TiKV-CDC instance number
      --kvcdc.binpath string             TiKV-CDC instance binary path
      --kvcdc.config string              TiKV-CDC instance configuration file
      --kvcdc.version string             TiKV-CDC instance version
      --mode string                      TiUP playground mode: 'tidb', 'tidb-cse', 'tiflash-disagg', 'tikv-slim' (default "tidb")
      --pd int                           PD instance number
      --pd.binpath string                PD instance binary path
      --pd.config string                 PD instance configuration file
      --pd.host host                     Playground PD host. If not provided, PD will still use host flag as its host
      --pd.mode string                   PD mode: 'pd', 'ms' (default "pd")
      --pd.port int                      Playground PD port. If not provided, PD will use 2379 as its port
      --port-offset int                  If specified, all components will use default_port+port_offset as the port. This argument is useful when you want to start multiple playgrounds on the same host. Recommend to set to 10000, 20000, etc.
      --pump int                         Pump instance number
      --pump.binpath string              Pump instance binary path
      --pump.config string               Pump instance configuration file
      --scheduling int                   Scheduling instance number
      --scheduling.binpath string        Scheduling instance binary path
      --scheduling.config string         Scheduling instance configuration file
  -T, --tag string                       Specify a tag for playground, data dir of this tag will not be removed after exit
      --ticdc int                        TiCDC instance number
      --ticdc.binpath string             TiCDC instance binary path
      --ticdc.config string              TiCDC instance configuration file
      --ticdc.host host                  Playground TiCDC host. If not provided, TiDB will still use host flag as its host
      --ticdc.port int                   Playground TiCDC port. If not provided, TiCDC will use 8300 as its port
      --tiflash int                      TiFlash instance number, when --mode=tidb-cse or --mode=tiflash-disagg this will set instance number for both Write Node and Compute Node
      --tiflash.binpath string           TiFlash instance binary path, when --mode=tidb-cse or --mode=tiflash-disagg this will set binary path for both Write Node and Compute Node
      --tiflash.compute int              TiFlash Compute instance number, available when --mode=tidb-cse or --mode=tiflash-disagg, take precedence over --tiflash
      --tiflash.compute.binpath string   TiFlash Compute instance binary path, available when --mode=tidb-cse or --mode=tiflash-disagg, take precedence over --tiflash.binpath
      --tiflash.compute.config string    TiFlash Compute instance configuration file, available when --mode=tidb-cse or --mode=tiflash-disagg, take precedence over --tiflash.config
      --tiflash.config string            TiFlash instance configuration file, when --mode=tidb-cse or --mode=tiflash-disagg this will set config file for both Write Node and Compute Node
      --tiflash.timeout int              TiFlash max wait time in seconds for starting, 0 means no limit (default 120)
      --tiflash.write int                TiFlash Write instance number, available when --mode=tidb-cse or --mode=tiflash-disagg, take precedence over --tiflash
      --tiflash.write.binpath string     TiFlash Write instance binary path, available when --mode=tidb-cse or --mode=tiflash-disagg, take precedence over --tiflash.binpath
      --tiflash.write.config string      TiFlash Write instance configuration file, available when --mode=tidb-cse or --mode=tiflash-disagg, take precedence over --tiflash.config
      --tiproxy int                      TiProxy instance number
      --tiproxy.binpath string           TiProxy instance binary path
      --tiproxy.config string            TiProxy instance configuration file
      --tiproxy.host host                Playground TiProxy host. If not provided, TiProxy will still use host flag as its host
      --tiproxy.port int                 Playground TiProxy port. If not provided, TiProxy will use 6000 as its port
      --tiproxy.timeout int              TiProxy max wait time in seconds for starting, 0 means no limit (default 60)
      --tiproxy.version string           TiProxy instance version
      --tso int                          TSO instance number
      --tso.binpath string               TSO instance binary path
      --tso.config string                TSO instance configuration file
  -v, --version                          version for tiup
      --without-monitor                  Don't start prometheus and grafana component

Use "tiup [command] --help" for more information about a command.

/usr/bin/server --help
bootstrap a mirror server

Usage:
  /usr/bin/server <root-dir> [flags]

Flags:
      --addr string       addr to listen (default "0.0.0.0:8989")
  -h, --help              help for /usr/bin/server
      --key-dir string    specify the directory where stores the private keys
      --upstream string   specify the upstream mirror (default "https://tiup-mirrors.pingcap.com")
  -v, --version           version for /usr/bin/server

/usr/bin/tiup --help
Please check for root manifest file, you may download one from the repository mirror, or try `tiup mirror set` to force reset it.
Error: initial repository from mirror(https://tiup-mirrors.pingcap.com/) failed: error loading manifest root.json: open /root/.tiup/bin/root.json: no such file or directory

The tiup command is giving an error as https://tiup-mirrors.pingcap.com/ currently yields 'access denied' in the XML response file.

[ottok]

Are the Markdown pages at https://github.com/pingcap/tiup/tree/master/doc/user automatically published somewhere? At least not at https://docs.pingcap.com/, since that site seems to be generated out of https://github.com/pingcap/docs? On a quick glance it looks like the Overview page at https://docs.pingcap.com/tidb/stable/tiup-overview/ is not the same text as https://github.com/pingcap/tiup/blob/master/doc/user/overview.md. The latter one hasn't been updated for past 5 years based on git history.

It seems to me that the page https://docs.pingcap.com/tidb/stable/quick-start-with-tidb/ should be the primary documentation for anybody starting to use tiup, and maybe the subpages of https://docs.pingcap.com/tidb/stable/tiup-reference/ when looking up what individual commands do (although that reference isn't complete, e.g. 'tiup client' is missing).

Perhaps both the Markdown files and future man pages should be just short stubs with that suggest users to visit the relevant page in the docs portal? For example man tiup should tell the user about https://docs.pingcap.com/tidb/stable/tiup-reference/.

At least git commit log at https://github.com/pingcap/docs/commits/master/tiup shows it is actively maintained, so probably most up-to-date docs there.

[rpaik]

@ottok yes, all docs contents are from the docs repo.

Unfortunately, a lot of projects don't always have their markdown pages on GitHub up-to-date (unlike official docs). Should other TiUP docs pages be added to the SEE ALSO section of the man page draft above?