> ## Documentation Index
> Fetch the complete documentation index at: https://athanor.alexisbouchez.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Commands, flags, and configuration

## Commands

### `athanor serve`

Start the webhook server.

```bash theme={null}
athanor serve
```

Reads configuration from environment variables (or `/etc/athanor/env` via systemd).

### `athanor` (default)

Launch the interactive TUI to run workflows locally.

```bash theme={null}
# Interactive - pick a workflow
athanor

# Run a specific workflow
athanor --workflow .github/workflows/ci.yml

# Custom workflow directory
athanor --workflow-dir ./my-workflows
```

### Flags (Local Mode)

| Flag             | Default             | Description                                                |
| ---------------- | ------------------- | ---------------------------------------------------------- |
| `--workflow-dir` | `.github/workflows` | Directory to search for workflow files                     |
| `--workflow`     | *(none)*            | Path to a specific workflow file (skips the selection TUI) |

## Environment Variables (Server Mode)

### Required

| Variable         | Description                                    |
| ---------------- | ---------------------------------------------- |
| `WEBHOOK_SECRET` | GitHub webhook secret for signature validation |
| `GITHUB_TOKEN`   | Personal access token with `repo:status` scope |

### Server

| Variable        | Default                       | Description            |
| --------------- | ----------------------------- | ---------------------- |
| `LISTEN_ADDR`   | `:8080`                       | Address to listen on   |
| `WORKSPACE_DIR` | `/var/lib/athanor/workspaces` | Where repos are cloned |

### MicroVM

Set `KERNEL_PATH` to enable VM mode. If unset, steps run directly on the host.

| Variable          | Default                        | Description                                          |
| ----------------- | ------------------------------ | ---------------------------------------------------- |
| `KERNEL_PATH`     | *(none)*                       | Path to vmlinux kernel. Enables VM mode.             |
| `ROOTFS_PATH`     | `/var/lib/athanor/rootfs.ext4` | Base rootfs image                                    |
| `SSH_KEY_PATH`    | `/var/lib/athanor/vm-ssh-key`  | SSH private key for VM access                        |
| `VM_DISK_DIR`     | `/var/lib/athanor/vm-disks`    | Directory for per-VM rootfs copies                   |
| `VM_CPUS`         | `2`                            | vCPUs per VM                                         |
| `VM_MEMORY_MB`    | `2048`                         | RAM per VM in MB                                     |
| `VM_MAX_PARALLEL` | `0` (auto)                     | Max concurrent VMs. `0` = auto-detect from host RAM. |

### GitHub App (Optional)

For Checks API support with full logs. See [GitHub App Setup](/guides/github-app).

| Variable                      | Description                    |
| ----------------------------- | ------------------------------ |
| `GITHUB_APP_ID`               | GitHub App ID                  |
| `GITHUB_APP_INSTALLATION_ID`  | Installation ID                |
| `GITHUB_APP_PRIVATE_KEY_PATH` | Path to the `.pem` private key |

## HTTP Endpoints

| Method | Path          | Description                 |
| ------ | ------------- | --------------------------- |
| `GET`  | `/`           | Web dashboard               |
| `GET`  | `/health`     | Health check (returns `ok`) |
| `POST` | `/webhook`    | GitHub webhook receiver     |
| `GET`  | `/api/runs`   | Recent runs as JSON         |
| `GET`  | `/api/events` | SSE stream of run updates   |

## Make Targets

| Target                            | Description                             |
| --------------------------------- | --------------------------------------- |
| `make build`                      | Build binary to `bin/athanor`           |
| `make build-linux`                | Cross-compile for Linux (arm64 + amd64) |
| `make test`                       | Run all tests                           |
| `make vet`                        | Run `go vet ./...`                      |
| `make run`                        | Build and launch the TUI                |
| `make run-workflow WORKFLOW=path` | Build and run a specific workflow       |
| `make clean`                      | Remove build artifacts                  |