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
6.3 KiB
6.3 KiB
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.
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:
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.
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.
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:
grm start prod-runner
# Override stored values:
grm start prod-runner --host 192.168.1.11 --user root
stop
Stop a registered Gitea Runner.
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.
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.
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:
grm disable prod-runner --token <token>
status
Check the status of a registered Gitea Runner.
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.
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:
grm remove prod-runner --token <token>
list
List all registered runners with live status.
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.