# CLI reference

All commands use the `mirror` entry point. Run `mirror --help` for the command
list and `mirror COMMAND --help` for command-specific usage.

## Global options

### mirror --version

```
mirror --version
```

Print the installed version and exit.

## Service commands

### mirror setup

```
mirror setup
```

Provision a Linux host for the daemon and worker. This command must run as
root. It verifies the required `rsync`, `lftp`, and `bandersnatch` executables,
creates the runtime, state, log, web, and configuration directories, and writes
the `mirror.service` and `mirror-worker.service` systemd units. It also runs
`systemctl daemon-reload` when `systemctl` is available.

If `/etc/mirror/config.json` does not exist, `setup` creates it from the built-in
default. An existing configuration is preserved.

### mirror daemon

```
mirror daemon [--config PATH]
```

Run the master daemon. It loads the configuration, starts the master Unix socket
server, maintains a supervised connection to the worker, and checks once per
second whether each package is due for synchronization.

| Option | Default | Description |
|--------|---------|-------------|
| `--config PATH` | `/etc/mirror/config.json` | Main configuration file. |

### mirror worker

```
mirror worker [--config PATH]
```

Run the worker server. The worker receives command RPCs, starts subprocesses
with the configured UID and GID, tracks them independently of the master, and
reports completion to connected master clients.

| Option | Default | Description |
|--------|---------|-------------|
| `--config PATH` | `/etc/mirror/config.json` | Main configuration file. The worker reads logging and socket settings from it. |

### mirror crontab

```
mirror crontab [-u USER] [-c CONFIG]
```

This command is currently a compatibility placeholder and produces no crontab
output.

| Option | Default | Description |
|--------|---------|-------------|
| `-u`, `--user USER` | `root` | Accepted for compatibility. |
| `-c`, `--config PATH` | `/etc/mirror/config.json` | Accepted for compatibility. |

## Daemon control commands

### mirror push

```
mirror push PACKAGEID [--config PATH]
```

Ask the running master to start a push-triggered sync for `PACKAGEID`. The
command forwards `SSH_ORIGINAL_COMMAND` and `SSH_CONNECTION` when present, so it
can be used as the forced command for an upstream push. A request for an already
running package succeeds with `already_running` status.

The master socket is read from `/var/run/mirror/master.sock.path` and otherwise
falls back to the default master socket. The accepted `--config` option is not
currently used for socket resolution.

| Argument / option | Default | Description |
|-------------------|---------|-------------|
| `PACKAGEID` | required | Package ID from the running daemon configuration. |
| `--config PATH` | `/etc/mirror/config.json` | Accepted for compatibility; currently unused. |

### mirror config reload

```
mirror config reload [--socket PATH] [--timeout SECONDS]
```

Ask the running master to reload its configuration. The result reports added,
removed, and modified packages plus any warnings. Settings that cannot be
changed safely at runtime remain at their current values and require a daemon
restart.

| Option | Default | Description |
|--------|---------|-------------|
| `--socket PATH` | Runtime metadata, then the default master socket | Explicit master socket path. |
| `--timeout SECONDS` | `30` | Seconds to wait for the daemon main loop to apply the reload. |

### mirror tui

```
mirror tui [--socket PATH]
```

Open the full-screen status UI. It polls the master once per second, shows
status counts and per-package timing, and follows the selected package's running
log or most recent completed log. Plain and gzip-compressed logs are loaded in
bounded, pageable windows. Columns adapt to the terminal width, and packages
from external sync plug-ins remain visible even when the TUI process has not
loaded that plug-in.

| Option | Default | Description |
|--------|---------|-------------|
| `--socket PATH` | Runtime metadata, then the default master socket | Explicit master socket path. |

Key bindings:

| Key | Action |
|-----|--------|
| `j`, `k`, up/down arrows | Move in the focused package or log pane. |
| `g`, `G`, `Home`, `End` | Jump to the first or last package, or the physical start or end of the focused log. |
| `PageUp`, `PageDown` | Page through the focused log, loading another disk window when needed. |
| `x` | Confirm and start or stop the selected package. |
| `l` | Toggle the log pane. |
| `Tab` | Move focus between the package table and log pane. |
| `s` | Cycle through default, status, last-success age, and package-ID sorting. |
| `/` | Edit the case-insensitive package-ID filter; `Enter` or `Esc` closes the input. |
| `p` | Pause or resume status polling. |
| `r` | Redraw the display. |
| `?` | Toggle the help overlay. |
| `q`, `Ctrl-C` | Exit. |

## Plug-in commands

### mirror plugin config create

```
mirror plugin config create PLUGIN [--config PATH] [--force | --no-force]
```

Load the main configuration, discover enabled external plug-ins, and call the
named plug-in's `create_config` callback. The plug-in owns the output path and
file contents. Existing files are skipped unless `--force` is supplied. Built-in
or external plug-ins without a `create_config` callback are rejected.

| Argument / option | Default | Description |
|-------------------|---------|-------------|
| `PLUGIN` | required | Registered plug-in name. |
| `--config PATH` | `/etc/mirror/config.json` | Main configuration used to discover plug-ins and resolve their settings. |
| `--force`, `--no-force` | `--no-force` | Allow the plug-in to overwrite its existing config file. |

## Standalone synchronization

### mirror standalone

```
mirror standalone SYNCTYPE [OPTIONS]
```

Run one sync in the foreground without the master daemon or worker server. The
command constructs an ad hoc package, dispatches it through the normal sync
plug-in, and executes delegated subprocesses in the current process. It returns
zero on success and the subprocess return code, or `1`, on failure. Standalone
runs do not write daemon `stat.json` or web status data.

Built-in values of `SYNCTYPE` are `rsync`, `ftpsync`, `lftp`, `bandersnatch`,
`local`, `ubuntu`, `jigdo`, `debmirror`, and `apt-mirror2`. The standalone
command currently validates against the built-in registry before loading
`--config`, so it does not discover external sync plug-ins.

| Argument / option | Default | Description |
|-------------------|---------|-------------|
| `SYNCTYPE` | required | Registered sync plug-in name. |
| `--src VALUE` | empty | Sync source URL or path. |
| `--dst VALUE` | empty | Local destination directory. |
| `-o`, `--option KEY=VALUE` | none | Set a sync option. Repeat `key[]=value` to build a list. Boolean strings and integers are converted to their JSON scalar types. |
| `--options-json JSON` | none | JSON object merged after `-o`; its keys take precedence. |
| `--uid INTEGER` | Current UID | User ID used by delegated subprocesses. |
| `--gid INTEGER` | Current GID | Group ID used by delegated subprocesses. |
| `--nice INTEGER` | `0` | Accepted niceness value. The current command does not propagate this value to the ad hoc package. |
| `--config PATH` | none | Load global settings such as hostname and ftpsync settings from an existing main configuration instead of using temporary defaults. It does not discover external plug-ins. |
| `--id PACKAGEID` | `standalone` | Internal package/job ID. |
| `--state-dir PATH` | Writable `/var/lib/mirror`, otherwise a temporary directory | State and temporary workspace, notably for `ftpsync`. The path is created when explicitly supplied. |

For example:

```
mirror standalone rsync \
  --src rsync://mirror.example/repository \
  --dst /srv/mirror/repository \
  -o exclude[]=project/trace \
  -o ffts=false
```

## Worker-side workflow commands

The `worker-execute` group contains specialized foreground workflows used by
the `ubuntu` and `jigdo` sync plug-ins. They do not connect to the daemon or
worker socket.

`apt-mirror2` and `debmirror` also perform repository discovery in the worker's
environment, but they use private Python wrapper entry points created by their
sync modules. They are not `mirror worker-execute` subcommands.

### mirror worker-execute ubuntu

```
mirror worker-execute ubuntu --src URL --dst PATH [OPTIONS]
```

Run the two-stage Ubuntu archive workflow: first copy data while excluding
archive metadata, then copy metadata and apply deletions.

| Option | Default | Description |
|--------|---------|-------------|
| `--src URL` | required | Rsync source URL or path. |
| `--dst PATH` | required | Local destination directory. |
| `--trace`, `--no-trace` | `--trace` | Write `<dst>/project/trace/<hostname>` after success. |
| `--trace-hostname HOSTNAME` | `socket.getfqdn()` | Trace filename hostname. |
| `--extra-rsync-arg ARG` | none | Argument appended to both rsync stages; repeatable. |
| `--stage1-exclude PATTERN` | Built-in metadata patterns | Stage-one exclude; repeatable. Supplying any value replaces all built-in defaults. |

### mirror worker-execute jigdo

```
mirror worker-execute jigdo --src URL --dst PATH \
  --jigdo-file CMD --debian-mirror URL [OPTIONS]
```

Run the Debian CD workflow: sync jigdo templates, reconstruct images with
`jigdo-mirror`, fetch the configured final ISO subset, and optionally write a
trace file.

| Option | Default | Description |
|--------|---------|-------------|
| `--src URL` | required | Rsync source URL or path for the Debian CD tree. |
| `--dst PATH` | required | Local `data/` root. |
| `--jigdo-file CMD` | required | Value written to `jigdoFile=` in `jigdo-mirror.conf`. |
| `--debian-mirror URL` | required | Value written to `debianMirror=`; normally a local Debian package mirror. |
| `--hostname HOSTNAME` | `socket.getfqdn()` | Hostname used by excludes and, unless overridden, the trace filename. |
| `--timeout SECONDS` | `7200` | Rsync timeout. |
| `--trace`, `--no-trace` | `--trace` | Write a trace file after success. |
| `--trace-path PATH` | `project/trace` | Trace directory relative to `dst`. |
| `--trace-hostname HOSTNAME` | Value of `--hostname` | Override the trace filename hostname. |
| `--template-exclude PATTERN` | `*.iso` | Phase-one exclude; repeatable. Supplying any value replaces the default. |
| `--final-include PATTERN` | Built-in businesscard, netinst, and i386 patterns | Final ISO include; repeatable. Supplying any value replaces all defaults. |
| `--extra-rsync-arg ARG` | none | Argument appended to both rsync phases; repeatable. |
| `--rsync-bin PATH` | `rsync` | Rsync executable. |
| `--jigdo-mirror-bin PATH` | `jigdo-mirror` | Jigdo mirror executable. |