# 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.

```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 |

## restart

Restart a registered Gitea Runner (stop, prune Docker images, start).

```bash
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.

```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 entirely.

```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:**

```text
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:

```text
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.

```bash
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:**

```bash
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.

```bash
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:**

```bash
grm trigger-workflow --list
grm trigger-workflow ci.yml --ref master
```

## --version

Show the installed GRM version.

```bash
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` |