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

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

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