grm/docs/user/cli-commands.md

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 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 completely
grm list	—	List all registered runners with live status
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

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.

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.

--version

Show the installed GRM version.

grm --version

This reports the version from __version__ in src/gitea_runner_manager/__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