# [tool-name](1): 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*.

<!--
Guidance: How to use this template
- A reference page describes; it does not teach. Put tutorials and how-to
  guides elsewhere and link to them from SEE ALSO.
- Keep the section order fixed. Readers of man pages jump to OPTIONS or
  EXIT STATUS without reading the rest.
- Generate as much as possible from the tool itself (for example from the
  argument parser) so this page cannot drift from `--help`.
- Every option row has the same columns: short form, long form, argument,
  default, description.
-->

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

## NAME

<!-- Guidance: The command name, a space-separated dash, and a one-line summary in lower case without a final full stop. -->

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

## SYNOPSIS

<!-- Guidance: Show every calling form. Square brackets mark optional parts, an ellipsis marks repetition, a vertical bar separates alternatives. -->

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

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

## DESCRIPTION

<!-- Guidance: Explain what the tool does, its model of operation and important behaviour (idempotency, side effects, network use) in neutral, factual sentences. -->

`[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

<!-- Guidance: Global options that apply to every command. One row per option, alphabetical by long form. Give the default and the environment variable that sets the same value, if any. -->

| 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

<!-- Guidance: One subsection per command with its own synopsis, description and option table. Keep the same layout for every command. -->

| 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

```text
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

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

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

### diff

```text
tool-name diff <source> <destination>
```

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

### login

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

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

### config

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

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

## ENVIRONMENT

<!-- Guidance: Every environment variable the tool reads, its effect and its precedence relative to options and the config file. -->

| 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

<!-- Guidance: Every file the tool reads or writes, with its purpose and platform-specific locations. -->

| 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

<!-- Guidance: Every exit code and its meaning. Scripts depend on these values, so treat changes as breaking. -->

| 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

<!-- Guidance: Realistic examples from simple to advanced. One line of explanation before each command. -->

Upload a folder and show what changed:

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

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

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

Download only images, limited to 20 MB/s:

```bash
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:

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

## DIAGNOSTICS

<!-- Guidance: Messages users most often see on stderr, with cause and remedy. -->

| 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

<!-- Guidance: Facts that do not fit elsewhere: security behaviour, compatibility, known limitations and where to report bugs. -->

- 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`.

## SEE ALSO

<!-- Guidance: Related commands, guides and external references. -->

`rsync(1)`, `[tool-name]-config(5)`, [Getting started tutorial], [How to
deploy a static site with tool-name], [Changelog].

## 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.