CLI Commands
GRM provides the following CLI commands for managing Gitea Actions runners. The base command is grm.
Command Summary
| Command | Arguments | Description |
|---|---|---|
grm install |
<host> |
Install and configure a runner on a remote host |
grm update |
<host> |
Update the gitea_runner binary on a remote host |
grm start |
<runner_name> |
Start a registered runner |
grm stop |
<runner_name> |
Stop a registered runner |
grm restart |
<runner_name> |
Restart a runner (stop, prune Docker images, start) |
grm enable |
<runner_name> |
Enable a runner to start on boot |
grm disable |
<runner_name> |
Disable and deregister a runner |
grm status |
<runner_name> |
Check the status of a registered runner |
grm remove |
<runner_name> |
Remove a runner entirely |
grm list |
— | List all registered runners with live status |
grm health |
[runner_name] |
Run health check (Docker, runner service, disk) on one or all runners |
grm trigger-workflow |
<workflow_id> |
Trigger a Gitea Actions workflow via the API |
grm --version |
— | Show the installed version |
Common lifecycle options
The start, stop, enable, status, disable, and remove commands all accept these override options. By default, connection details are read from the local registry (~/.local/share/grm/runners.json).
| 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 |
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 |
CI_GITEA_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 |
restart
Restart a registered Gitea Runner (stop, prune Docker images, start).
grm restart <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 entirely.
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.
The status is checked live by running an Ansible ad-hoc command on each remote host (systemctl --user is-active gitea-runner). Possible status values: active, inactive, failed, unknown.
Example output:
NAME HOST USER LABELS STATUS
------------------------------------------------------------------------------------------
prod-runner 192.168.1.10 ubuntu docker:docker://gitea/... active
build-runner 192.168.1.10 ubuntu docker:docker://gitea/... active
test-runner 192.168.1.20 ubuntu inactive
If no runners are registered:
No runners registered. Use 'grm install' to add one.
health
Run a health check on one or all registered runners. Checks Docker daemon status, Gitea runner service status, and disk space usage. Unhealthy services are automatically restarted by the healthcheck script.
grm health [runner_name] [options]
Arguments:
| Argument | Description |
|---|---|
runner_name |
(optional) Name of the runner to check. If omitted, checks all registered runners. |
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 health
# Check a specific runner:
grm health prod-runner
Output shows NAME, HOST, HEALTHY (yes/no), and MESSAGE columns. The command exits with code 1 if any runner is unhealthy.
The health check is also run automatically via a systemd timer installed by the Ansible role. See ansible/roles/gitea_runner/templates/runner-healthcheck.sh.j2 for the script and runner-healthcheck.timer.j2 for the timer.
trigger-workflow
Trigger a Gitea Actions workflow via the API.
grm trigger-workflow <workflow_id> [options]
grm trigger-workflow --list
Arguments:
| Argument | Description |
|---|---|
workflow_id |
Workflow filename (e.g., ci.yml) or ID |
Options:
| Option | Description |
|---|---|
--list |
List available workflows in the repository |
--ref |
Branch or tag to trigger on (default: repository default branch) |
Example:
grm trigger-workflow --list
grm trigger-workflow ci.yml --ref master
--version
Show the installed GRM version.
grm --version
This reports the version from __version__ in src/grm/__init__.py, which is the single source of truth set by the automated release pipeline.
Environment Variables
All CLI options can be set via environment variables (loaded from .env via python-dotenv). Command-line flags take precedence over environment variables.
| Variable | Used by | Description |
|---|---|---|
GITEA_URL |
install, disable, remove |
Gitea instance URL |
GITEA_REGISTRATION_TOKEN |
install, disable, remove |
Runner registration token |
CI_GITEA_TOKEN |
install |
Admin API token for integration test |
GITEA_INTEGRATION_RETRIES |
install |
API check retries (default: 3) |
GITEA_RUNNER_USER |
install, update |
Default SSH user |
GITEA_RUNNER_KEY |
install, update |
Default SSH key path |
GITEA_RUNNER_LABELS |
install |
Default runner labels |
GRM_LANG |
all | UI language: en, bg, de, ru, zh, pl |
GRM_LOG_LEVEL |
all | Console log level: DEBUG, INFO, WARNING, ERROR, CRITICAL |