CLI Reference Template (Man Page Sections)

Command-line reference in man-page order – synopsis, options, commands, environment, files, exit status, examples

文档与支持标准cli reference更新于 2026年10月20日

使用方法: Use for any command-line tool. Generate the options tables from the argument parser where possible, then write exit codes and examples. The main pitfall is drifting from the tool's --help output.

预览

tool-name: Command Reference

Reference page for a command-line tool, organised in the classic manual page sections: NAME, SYNOPSIS, DESCRIPTION, OPTIONS, COMMANDS, ENVIRONMENT, FILES, EXIT STATUS, EXAMPLES and SEE ALSO. Replace every [bracketed] value and every row marked Example.

Field	Value
Tool	[tool-name]
Version documented	[2.3.0]
Section	1 (user commands)
Owner	[@cli-maintainer]
Last updated	YYYY-MM-DD

NAME

[tool-name] - [synchronise local folders with a remote object store]

SYNOPSIS

tool-name [global-options] <command> [command-options] [arguments...]
tool-name --version
tool-name --help [command]

Notation: [ ] optional, < > required value, ... may repeat, | choose one.

DESCRIPTION

[tool-name] compares a local directory with a remote bucket and transfers the files that differ. Comparison uses file size and SHA-256 checksum; modification times are ignored unless --use-mtime is given. Transfers run in parallel and are resumable: an interrupted run continues from the last completed file when started again.

The tool never deletes remote files unless --delete is given. All network traffic uses HTTPS. Output is human-readable by default and machine-readable with --output json.

OPTIONS

Short	Long	Argument	Default	Description
`-c`	`--config`	`<path>`	`~/.config/tool-name/config.toml`	Read settings from this file
	`--dry-run`	none	off	Show what would change without changing anything
`-h`	`--help`	`[command]`	none	Print help for the tool or a command and exit
`-j`	`--jobs`	`<n>`	number of CPUs, maximum 16	Number of parallel transfers (1 to 64)
	`--no-color`	none	colour when stdout is a terminal	Disable coloured output
`-o`	`--output`	`text` or `json`	`text`	Output format
`-p`	`--profile`	`<name>`	`default`	Use the named credentials profile
`-q`	`--quiet`	none	off	Print errors only
`-v`	`--verbose`	none	off	Print each file decision; repeat (`-vv`) for HTTP details
`-V`	`--version`	none	none	Print version and exit

Options may appear before or after the command. A double dash (--) ends option parsing; later arguments are treated as paths.

COMMANDS

Command	Summary
`sync`	Make the destination match the source
`ls`	List remote objects
`diff`	Show differences without transferring
`login`	Store credentials for a profile
`config`	Read or write configuration values

sync

tool-name sync [options] <source> <destination>

Copies new and changed files from source to destination. Either side may be a local path or a remote URL of the form remote://bucket/prefix.

Short	Long	Argument	Default	Description
	`--delete`	none	off	Delete destination files that do not exist in the source
`-x`	`--exclude`	`<glob>`	none	Skip matching paths; may repeat
	`--use-mtime`	none	off	Treat a newer modification time as a change
	`--max-bandwidth`	`<rate>`	unlimited	Limit throughput, for example `20MB/s`

ls

tool-name ls [--recursive] [--long] <remote-url>

Lists objects under a prefix. --long adds size, checksum and last-modified time.

diff

tool-name diff <source> <destination>

Prints one line per difference: + only in source, - only in destination, ~ content differs.

login

tool-name login [--profile <name>]

Opens a browser for single sign-on and stores a refresh token in the operating system keychain.

config

tool-name config get <key>
tool-name config set <key> <value>

Reads or writes a value in the configuration file. See FILES.

ENVIRONMENT

Variable	Equivalent option	Description
`TOOLNAME_PROFILE`	`--profile`	Default credentials profile
`TOOLNAME_CONFIG`	`--config`	Path to the configuration file
`TOOLNAME_TOKEN`	none	Access token; overrides stored credentials (use in CI)
`TOOLNAME_JOBS`	`--jobs`	Default parallelism
`NO_COLOR`	`--no-color`	Any non-empty value disables colour
`HTTPS_PROXY`	none	Proxy for all network traffic

Precedence, highest first: command-line option, environment variable, configuration file, built-in default.

FILES

Path	Purpose
`~/.config/tool-name/config.toml`	User configuration (Windows: `%APPDATA%\tool-name\config.toml`)
`/etc/tool-name/config.toml`	System-wide defaults, read before the user file
`~/.cache/tool-name/state.db`	Resume state for interrupted transfers; safe to delete
`.toolnameignore`	Per-directory exclude patterns, one glob per line

EXIT STATUS

Code	Meaning
0	Success; destination matches source
1	General error
2	Invalid usage: unknown option or missing argument
3	Authentication failed or credentials expired
4	Some files failed to transfer; others succeeded
5	Network unreachable after retries
130	Interrupted by the user (Ctrl+C)

EXAMPLES

Upload a folder and show what changed:

tool-name sync -v ./site remote://www-assets/site

Preview a mirror that deletes stale remote files, without changing anything:

tool-name sync --delete --dry-run ./site remote://www-assets/site

Download only images, limited to 20 MB/s:

tool-name sync -x '*' -x '!*.png' -x '!*.jpg' --max-bandwidth 20MB/s remote://media/2026 ./media

Use in CI with a token and JSON output, failing the job on partial errors:

TOOLNAME_TOKEN="$DEPLOY_TOKEN" tool-name sync -o json ./dist remote://prod-web/ > sync-report.json

DIAGNOSTICS

Message	Cause	Remedy
`error: credentials expired for profile 'default'`	Refresh token older than 30 days	Run `tool-name login`
`warning: 3 files skipped (permission denied)`	Local files not readable	Check file permissions; exit status is 4
`error: unknown option '--del'`	Typo or abbreviated option	Use the full option name; exit status is 2

NOTES

Credentials are stored in the operating system keychain, never in the configuration file. TOOLNAME_TOKEN is not written to disk.
Paths are compared case-sensitively, including on macOS and Windows; two local files that differ only in case cause exit status 4.
Symbolic links are followed for files and skipped for directories.
Report bugs at [https://github.com/example/tool-name/issues] with the output of tool-name --version and the failing command run with -vv.

Standard and licence note

Based on the conventional section layout of Unix manual pages (NAME, SYNOPSIS, DESCRIPTION, OPTIONS, ENVIRONMENT, FILES, EXIT STATUS, EXAMPLES, SEE ALSO), a long-standing convention. Template licence: MIT.