homerail-cli

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# HomeRail CLI (TypeScript)

## Manager Agent native shell

The HomeRail Manager Agent can use the selected harness's native shell directly:
Codex provides its built-in shell and Claude Agent SDK provides `Bash`.

Prefer `hr --json <command...>` for structured results. If `hr` is not installed
on `PATH`, HomeRail exposes the active local-source entrypoint through
`HOMERAIL_CLI_ENTRYPOINT`; invoke it as:

```bash
node "$HOMERAIL_CLI_ENTRYPOINT" --json <command...>
```

A zero exit status plus the returned JSON is valid execution evidence. Dedicated
Manager Tools remain useful shortcuts, but the CLI is the complete control
surface for commands that have no dedicated Tool.

## Installation

Before acting, apply `homerail-shared` rules. This pre-publication release uses the local source tree; do not assume npm publication exists.

```bash
cd homerail_cli
npm ci
npm run build
```

The CLI binary is `dist/cli.js`. Run it directly or via the `hr` bin alias:

```bash
# From the repo root after build
node homerail_cli/dist/cli.js --help

# Or link globally
cd homerail_cli && npm link
hr --help
```

For development without a build step:

```bash
npx tsx homerail_cli/src/cli.ts --help
```

## Configuration

Use the CLI config flow for local runtime settings and provider credentials:

```bash
hr config
hr config show
hr config apply
```

`hr config` writes non-secret settings under `${HOMERAIL_HOME}/config.json`.
Provider and integration credentials are sent to Manager and stored in the
Manager encrypted settings store, persisted under
`${HOMERAIL_HOME}/manager/homerail.db`. `${HOMERAIL_HOME}/secrets/env` is a
legacy plaintext import path only; do not use it as the normal OSS
configuration path.

The Manager URL is resolved in this order:

1. `--base-url <url>` flag on any command
2. `HOMERAIL_MANAGER_URL` environment variable
3. `${HOMERAIL_HOME}/config.json`
4. Default: `http://localhost:19191`

The default Manager port is `19191`. Override it with `HOMERAIL_MANAGER_PORT` for
local service startup, or use a full `HOMERAIL_MANAGER_URL` / `--base-url` when the
Manager is on another host or port.
The default Agent UI HTTPS port is `19192`. Override it with `HOMERAIL_UI_PORT` or
`ui.port` in local config. The HTTP fallback port is `19193`; override it with
`HOMERAIL_UI_HTTP_PORT` or `ui.httpPort`.

```bash
# Option A: environment variable
export HOMERAIL_MANAGER_PORT=19191
export HOMERAIL_MANAGER_URL=http://localhost:${HOMERAIL_MANAGER_PORT}

# Option B: per-command flag
hr --base-url http://localhost:19191 templates list
```

Additional global options:

| Flag | Description |
|------|-------------|
| `--json` | Output raw JSON instead of formatted text |
| `--request-timeout <ms>` | HTTP request timeout (default: 30000) |

## Commands

### Local Runtime

```bash
# Interactive local config
hr config

# Start Manager and Node together
hr start
hr start --rebuild-worker-image
hr start --ui
hr start --ui --enable-text-mode

# Inspect and stop services started by hr start
hr runtime status
hr runtime logs
hr runtime stop

# Start and stop the decoupled Agent UI
hr ui start
hr ui start --enable-text-mode
hr ui status
hr ui logs
hr ui stop

From xiaotianfotos/homerail, MIT.

More from xiaotianfotos/homerail