scripts/docs/CLI.md

# Command line

Every script is its own program, and there is no global command. The reference below is
taken from each script's own `--help`; if the two disagree, the program is right and
this file is a defect.

Common to all six: `--version` prints the version and exits, `-h` / `--help` prints the
usage and exits, options are given as `--name value` or `--name=value`, and an unknown
option is refused with the usage and exit code 2.

## network-diag.pl

```
Usage: network-diag.pl [options]

Network diagnostics: latency, DNS, MTU, dual-stack, ports

Options:
  --target HOST     Target host for tests (default: cloudflare.com)
  --protocol FAMILY Address family: auto (dual-stack), v4 (IPv4 only),
                    v6 (IPv6 only) (default: auto)
  --version         Show the version and exit
  -h, --help        Show this help and exit
```

| Flag | Default | Effect |
|---|---|---|
| `--target HOST` | `cloudflare.com` | The host pinged, resolved and probed for MTU |
| `--protocol FAMILY` | `auto` | `auto` measures both families, `v4` and `v6` restrict the run |

Runs without root. Ports belonging to other users are reported as `(no permission)`
rather than silently dropped.

## system-diag.pl

```
Usage: system-diag.pl [options]

System diagnostics: CPU, memory, disk, network, GPU, services, security, performance

Options:
  --section LIST   Comma-separated sections to run. Available: overview, cpu, memory, disk, network, gpu, services, security, performance, issues  [default: all]
  --external-ip    Also detect external IP addresses via icanhazip.com (sends a request to a third-party service)
  --json           Output machine-readable JSON to stdout
  --version        Show the version and exit
  -h, --help       Show this help and exit
```

| Flag | Default | Effect |
|---|---|---|
| `--section LIST` | all | Runs only the named sections |
| `--external-ip` | off | Sends a request to `icanhazip.com` to report the public address |
| `--json` | off | Writes the JSON document to stdout instead of the report |

Runs without root; some figures need it and are reported as unavailable instead. Colour
is used only on a terminal and is suppressed by `NO_COLOR`. The report goes to stderr,
so `--json` keeps stdout clean.

## server-setup.pl

```
Usage: server-setup.pl [options]

Idempotent server setup for Fedora Server, CentOS Stream and openEuler

Options:
  --dry-run             Print what would be done without making changes
  --skip-update         Skip system update
  --skip-packages       Skip base package installation
  --skip-epel           Skip EPEL repository setup on CentOS
  --skip-firewall       Skip firewall setup
  --skip-selinux        Skip SELinux configuration
  --skip-podman         Skip Podman installation
  --skip-auto-updates   Skip automatic updates configuration
  --version             Show the version and exit
  -h, --help            Show this help and exit
```

Needs root. The `--skip-*` flags exist per section so a section can be left to another
tool; the sections are ordered update, EPEL, packages, firewall, SELinux, Podman,
automatic updates.

## workstation-setup.pl

```
Usage: workstation-setup.pl [options]

Idempotent workstation setup for Fedora

Options:
  --dry-run        Print what would be done without making changes
  --skip-update    Skip system update
  --skip-rpm       Skip RPM package installation
  --skip-flatpak   Skip Flatpak apps
  --skip-repos     Skip adding third-party repos
  --skip-remove    Skip removing pre-installed apps
  --skip-go        Skip Go toolchain installation
  --skip-rust      Skip Rust toolchain installation
  --skip-jetbrains Skip JetBrains IDE installation
  --skip-firewall  Skip firewall setup
  --skip-selinux   Skip SELinux setup
  --version        Show the version and exit
  -h, --help       Show this help and exit
```

Needs root, and targets Fedora only. The Go toolchain and GoLand are downloaded and
verified by checksum; Brave's repository key is verified by fingerprint before import.

## sglang-deploy.pl

```
Usage: sglang-deploy.pl [options]

  --model ID                     ModelScope model ID (menu when omitted)
  --port N                       internal engine port (default: 8000, not 443)
  --tensor-parallel N            GPUs for tensor parallelism (default: 1, written as
                                 the engine's --tp-size)
  --max-model-len N              context length (default: 4096, written as the
                                 engine's --context-length)
  --gpu-memory-utilization F     static memory fraction (default: 0.90, written as
                                 the engine's --mem-fraction-static)
  --state-dir PATH               state and model cache directory (default: /opt/sglang)
  --service-name NAME            systemd service name (default: sglang)
  --cert-dir PATH                TLS certificate directory (default: /etc/ssl/sglang)
  --image TAG                    engine image (default: resolved from the GPU and
                                 the newest SGLang release; a Radeon card resolves
                                 AMD's newest dated gfx1151 build)
  --rocm-flavour NAME            ROCm flavour of the image (default: from the host
                                 ROCm; rocm10, rocm724, rocm720 or rocm700)
  --api-key KEY                  API key for the endpoint (default: generate and
                                 store in /etc/sysconfig)
  --dry-run                      preview without making changes
  --uninstall                    tear down the service, container, caddy drop-in
                                 and certificates
  --help                         show this help
  --version                      show the version
```

Needs root. Without `--model` an interactive menu offers GLM 5.3, GLM 5.3 Flash,
Qwen 3.8 Max, Qwen 3.8 Flash and DeepSeek V4.1 Flash, plus a free-form entry.
`--tensor-parallel`, `--max-model-len` and `--gpu-memory-utilization` are
written to the unit as the engine's own `--tp-size`, `--context-length` and
`--mem-fraction-static`. The API key is shown once when it is generated; a key given
with `--api-key` is never echoed. `--uninstall` stops and disables the service, removes
the unit, the container, the caddy drop-in and the certificates, and keeps the
image and the model cache.

## system-optimise.pl

```
Usage: system-optimise.pl [options]

Idempotent system cleanup and optimisation for Fedora, CentOS Stream and openEuler

Options:
  --dry-run       Preview without making changes
  --skip-dnf      Skip DNF cleanup (autoremove, old kernels, cache)
  --skip-journal  Skip journal vacuum
  --skip-tmp      Skip temp file cleanup
  --skip-cores    Skip core dump cleanup
  --version       Show the version and exit
  -h, --help      Show this help and exit
```

Needs root. The running kernel and one fallback are always kept. Both dnf generations
are driven: Fedora ships dnf 5, CentOS Stream 10 and openEuler ship dnf 4.

## Exit codes

| Code | Meaning |
|---|---|
| `0` | The run completed, and every step it attempted succeeded |
| `1` | A step failed, a required tool is missing, the hardware does not qualify, or the system is unsupported |
| `2` | The arguments were wrong, or interactive input was needed and stdin is not a terminal |

A run that finishes with failed steps prints them at the end of the summary and exits 1,
so a pipeline notices even when the failure was not fatal.

## Examples

```sh
# Is the connection healthy, and is IPv6 working?
perl network-diag.pl --target example.org --protocol auto

# The same machine's health as JSON, for a monitoring poll
perl system-diag.pl --json --section cpu,memory,disk

# A new server, seen before it is changed
sudo perl server-setup.pl --dry-run

# Cleanup, leaving journals and core dumps alone
sudo perl system-optimise.pl --skip-journal --skip-cores

# Deploy a model and then take it down again
sudo perl sglang-deploy.pl --model deepseek-ai/DeepSeek-V4-Flash-0731
sudo perl sglang-deploy.pl --uninstall
```