emil
5b05db4e6d
Add /docs/ directory with user and technical documentation extracted from README, AGENTS.md, and source code. Add scripts/sync_wiki.py to sync docs to Gitea wiki via API. Add scripts/doc_coverage.py to check CLI commands, modules, and CI scripts are documented. Add sync-wiki.yml workflow for auto-sync on merge and release. Slim down README.md to lean entry point. 28 new unit tests, 100% coverage maintained. Closes GRM-36
234 lines
6.3 KiB
Markdown
234 lines
6.3 KiB
Markdown
# CLI Commands
|
|
|
|
GRM provides the following CLI commands for managing Gitea Actions runners. The base command is `grm`.
|
|
|
|
## install
|
|
|
|
Install and configure a Gitea Runner on a remote host.
|
|
|
|
```bash
|
|
grm install <host> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `host` | Remote host (IP address or hostname) |
|
|
|
|
**Options:**
|
|
|
|
| Option | Short | Default | Description |
|
|
|--------|-------|---------|-------------|
|
|
| `--user` | `-u` | `GITEA_RUNNER_USER` env or current login | SSH user |
|
|
| `--key` | `-k` | `GITEA_RUNNER_KEY` env | Path to SSH private key |
|
|
| `--name` | `-n` | hostname | Gitea Runner name |
|
|
| `--token` | `-t` | `GITEA_REGISTRATION_TOKEN` env | Registration token |
|
|
| `--url` | — | `GITEA_URL` env | Gitea URL |
|
|
| `--admin-token` | `-a` | `REPO_TOKEN` env | Gitea admin API token for integration test |
|
|
| `--integration-retries` | `-r` | `3` (`GITEA_INTEGRATION_RETRIES` env) | Integration test API retries |
|
|
| `--labels` | `-l` | `GITEA_RUNNER_LABELS` env | Runner labels for Gitea Actions. Example: `docker:docker://alpine:latest` |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | `--ask-become-pass` | Prompt for sudo password (default) or skip it |
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
grm install 192.168.1.10 --user ubuntu --key ~/.ssh/id_ed25519 --name prod-runner
|
|
```
|
|
|
|
## update
|
|
|
|
Update the Gitea Runner binary on a remote host.
|
|
|
|
```bash
|
|
grm update <host> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `host` | Remote host (IP address or hostname) |
|
|
|
|
**Options:**
|
|
|
|
| Option | Short | Default | Description |
|
|
|--------|-------|---------|-------------|
|
|
| `--user` | `-u` | `GITEA_RUNNER_USER` env or current login | SSH user |
|
|
| `--key` | `-k` | `GITEA_RUNNER_KEY` env | Path to SSH private key |
|
|
| `--version` | `-v` | — | Specific Gitea Runner version |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | `--ask-become-pass` | Prompt for sudo password (default) or skip it |
|
|
|
|
## start
|
|
|
|
Start a registered Gitea Runner.
|
|
|
|
```bash
|
|
grm start <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options (common lifecycle options):**
|
|
|
|
| Option | Short | Description |
|
|
|--------|-------|-------------|
|
|
| `--host` | — | Override host from registry |
|
|
| `--user` | `-u` | Override user from registry |
|
|
| `--key` | `-k` | Override SSH key from registry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
grm start prod-runner
|
|
# Override stored values:
|
|
grm start prod-runner --host 192.168.1.11 --user root
|
|
```
|
|
|
|
## stop
|
|
|
|
Stop a registered Gitea Runner.
|
|
|
|
```bash
|
|
grm stop <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options (common lifecycle options):**
|
|
|
|
| Option | Short | Description |
|
|
|--------|-------|-------------|
|
|
| `--host` | — | Override host from registry |
|
|
| `--user` | `-u` | Override user from registry |
|
|
| `--key` | `-k` | Override SSH key from registry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
|
|
|
|
## enable
|
|
|
|
Enable a registered Gitea Runner to start on boot.
|
|
|
|
```bash
|
|
grm enable <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options (common lifecycle options):**
|
|
|
|
| Option | Short | Description |
|
|
|--------|-------|-------------|
|
|
| `--host` | — | Override host from registry |
|
|
| `--user` | `-u` | Override user from registry |
|
|
| `--key` | `-k` | Override SSH key from registry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
|
|
|
|
## disable
|
|
|
|
Disable a registered Gitea Runner and deregister it.
|
|
|
|
```bash
|
|
grm disable <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options:**
|
|
|
|
| Option | Short | Default | Description |
|
|
|--------|-------|---------|-------------|
|
|
| `--host` | — | from registry | Override host from registry |
|
|
| `--user` | `-u` | from registry | Override user from registry |
|
|
| `--key` | `-k` | from registry | Override SSH key from registry |
|
|
| `--token` | `-t` | `GITEA_REGISTRATION_TOKEN` env | Registration token |
|
|
| `--url` | — | `GITEA_URL` env | Gitea URL |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | `--ask-become-pass` | Prompt for sudo password (default) or skip it |
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
grm disable prod-runner --token <token>
|
|
```
|
|
|
|
## status
|
|
|
|
Check the status of a registered Gitea Runner.
|
|
|
|
```bash
|
|
grm status <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options (common lifecycle options):**
|
|
|
|
| Option | Short | Description |
|
|
|--------|-------|-------------|
|
|
| `--host` | — | Override host from registry |
|
|
| `--user` | `-u` | Override user from registry |
|
|
| `--key` | `-k` | Override SSH key from registry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | Prompt for sudo password (default) or skip it |
|
|
|
|
## remove
|
|
|
|
Remove a registered Gitea Runner completely.
|
|
|
|
```bash
|
|
grm remove <runner_name> [options]
|
|
```
|
|
|
|
**Arguments:**
|
|
|
|
| Argument | Description |
|
|
|----------|-------------|
|
|
| `runner_name` | Name of the registered runner |
|
|
|
|
**Options:**
|
|
|
|
| Option | Short | Default | Description |
|
|
|--------|-------|---------|-------------|
|
|
| `--host` | — | from registry | Override host from registry |
|
|
| `--user` | `-u` | from registry | Override user from registry |
|
|
| `--key` | `-k` | from registry | Override SSH key from registry |
|
|
| `--token` | `-t` | `GITEA_REGISTRATION_TOKEN` env | Registration token |
|
|
| `--url` | — | `GITEA_URL` env | Gitea URL |
|
|
| `--force` | `-f` | — | Skip remote cleanup and only remove the local registry entry |
|
|
| `--ask-become-pass/--no-ask-become-pass` | — | `--ask-become-pass` | Prompt for sudo password (default) or skip it |
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
grm remove prod-runner --token <token>
|
|
```
|
|
|
|
## list
|
|
|
|
List all registered runners with live status.
|
|
|
|
```bash
|
|
grm list
|
|
```
|
|
|
|
This command takes no arguments or options. It displays a table with columns: NAME, HOST, USER, LABELS, STATUS for all runners stored in the local registry at `~/.local/share/grm/runners.json`.
|