oblachno-oss/grm
3
0
Fork 0
Code Issues 26 Pull Requests 1 Actions Packages Projects Releases 17 Wiki Activity
Files
ea2f0cc6004c82bfbe9441e7a6b68ea13512017a
grm/docs/user/cli-commands.md
T
emil ea2f0cc600
Post-merge / detect-type (push) Successful in 51s
Details
Post-merge / release (push) Successful in 54s
Details
Post-merge / validate-commit-msg (push) Successful in 1m5s
Details
Post-merge / publish (push) Has been skipped
Details
Post-merge / badges (push) Successful in 1m17s
Details
Post-merge / vikunja (push) Successful in 1m26s
Details
Post-merge / configure-repo (push) Successful in 1m12s
Details
Post-merge / sync-wiki (push) Successful in 1m34s
Details
GRM-117: fix: fix wiki link URLs, heading hierarchy, quote pip install vars
2026-06-28 17:07:11 +00:00

304 lines
9.5 KiB
Markdown
Raw Blame History

# 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.
```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` | `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:**
```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`.
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.
```bash
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` |
Reference in New Issue View Git Blame Copy Permalink