homerail-cli

name	homerail-cli
description	HomeRail CLI syntax, flags, configuration, and command reference. Use to translate a known operation into an exact hr command or diagnose CLI configuration. Use homerail-dag-ops for the full DAG design, execution, supervision, and inspection workflow. For deployment, service startup, or skill installation, use homerail-install-ops first.

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:

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.

cd homerail_cli
npm ci
npm run build

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

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

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

Configuration

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

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.

# 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

# 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

# Check readiness
hr doctor

hr start is service-first: missing provider credentials should not prevent Manager and Node from starting. hr doctor is the readiness gate that reports missing model configuration and Manager Agent harness compatibility before DAGs or Manager Agent smokes can run. Use --rebuild-worker-image after changing homerail_worker source so provisioned DAG workers run the current checkout instead of a stale local Docker image. Use hr start --ui or hr ui start to run the Agent UI. HTTPS is the primary local endpoint (https://localhost:19192) and HTTP remains available as a fallback (http://localhost:19193). The UI processes use ${HOMERAIL_HOME}/pids/ui-https.pid / ${HOMERAIL_HOME}/logs/ui-https.log and ${HOMERAIL_HOME}/pids/ui.pid / ${HOMERAIL_HOME}/logs/ui.log; hr runtime stop also stops both. Agent UI text mode is temporarily disabled by default, so /agent opens the Voice Agent cockpit directly. Use --enable-text-mode only when restoring the text Agent shell for local debugging.

Templates and Runs

# List available orchestration templates
hr templates list
hr --json templates list

# Start a DAG run from a public YAML template path
hr run assets/orchestrations/public-two-node.yaml.template \
  --prompt "<prompt>"

# Sync a DAG asset to the Manager database. The YAML workflow_id is the stable
# identity; keep it unchanged during AI edits unless creating a new workflow/version.
hr dag sync assets/orchestrations/public-dev-5node.yaml.template

# Sync a DB-backed runtime profile. Profile YAML references model_alias or
# llm_setting_id, not provider/model.
hr profile sync assets/profiles/example-runtime.profile.yaml.template \
  --workflow public-dev-5node-template

# Run the database DAG instance with a server-side runtime profile
hr run \
  --workflow public-dev-5node-template \
  --profile example-runtime \
  --prompt "<prompt>"

# One-shot convenience: sync asset and profile YAML, then run the DB instance
hr run assets/orchestrations/public-dev-5node.yaml.template \
  --sync \
  --profile assets/profiles/example-runtime.profile.yaml.template \
  --prompt "<prompt>"

# Pin a specific database LLM setting for this run when needed
hr run assets/orchestrations/public-two-node.yaml.template \
  --setting-id <llm_setting_id> \
  --prompt "<prompt>"

# Run a read-only local harness deployment diagnosis from a fresh clone.
# The agent files an issue only when deployment is blocked.
hr run assets/orchestrations/local-harness-cli-deploy-diagnosis.yaml.template \
  --prompt "source_repo_url=<https git url> branch=main"

# List recent runs
hr runs

# Check run status
hr status <run_id>
hr --json status <run_id>

# Stop a running DAG
hr stop <run_id>

The deployment diagnosis template is a normal DAG. Do not start a fixed host Worker and do not mount Docker into the Worker. The run should be provisioned through Node like any other DAG, use its isolated workspace, clone the latest source, build it, configure the cloned CLI to talk to the outer Manager, and verify runtime status / doctor. The template uses advisory scorecard enforcement, so scorecard findings should be reviewed separately from the deployment result unless a template explicitly opts into strict enforcement.

Smoke Gates

# Live DAG smoke through Manager create-and-run
hr smoke dag \
  --template assets/orchestrations/public-dev-5node.yaml.template

# Live Manager Agent smoke through /api/manager/chat
hr smoke manager-agent

# Validate a specific configured Manager Agent runtime
hr smoke manager-agent --setting-id <llm_setting_id>
hr smoke manager-agent --provider <provider_id> --model <model_name>

smoke manager-agent verifies the configured Manager Agent harness can call Manager tools. It requires /api/manager/chat to return a real run_id, then waits for the deterministic two-node DAG to reach completed.

DAG Supervision and Inspection

For asynchronous work, follow homerail-dag-ops: subscribe and await an event through the current host; the bundled helper supports blocking JSON output. The commands below are syntax references for foreground inspection, not a sequence to repeat during unchanged progress.

# Foreground operator supervision (not an autonomous model polling loop)
hr dag supervise <run_id>

# One requested cursor snapshot
hr dag supervise <run_id> --tick --cursor <cursor>

# Foreground interval watch when explicitly needed by the operator
hr dag watch <run_id> --interval 5 --timeout 600

# Quick status snapshot
hr dag quick <run_id> --events 10

# Per-node chat and tool activity
hr dag chats <run_id> --tools 5
hr dag chats <run_id> --node node-a node-b
hr dag chats <run_id> --tools 20 --raw-tools

# Handoff content and contract checks
# --content-limit caps each handoff's content; default 500 truncates long JSON.
# Pass 0 (or a large value) to see the full review/summary payload.
hr dag handoffs <run_id> --content-limit 0

Use --raw-tools only for audit/debug. It prints redacted tool inputs and result previews so an operator can verify CLI-first behavior, detect forbidden Write/Edit/MultiEdit use, or spot direct API calls. For local deep debugging only, Worker raw audit files are stored per run under ${HOMERAIL_HOME}/audit/tool-events/<run_id>.jsonl; older installs may still have legacy ${HOMERAIL_HOME}/audit/tool-events.jsonl archives.

Evaluation and Reporting

# Run scorecard
hr scorecard <run_id>

# Evaluation report
hr eval-run <run_id> --events 5 --tools 3

# Replay log
hr replay <run_id>

Scorecard policies are advisory by default. hr scorecard still reports findings, but eval-run only treats scorecard findings as gating failures when the template declares scorecard.enforcement: strict.

Utilities

# Configure the MiMo token-plan preset through local config
hr config
hr config apply

# List configured LLM providers
hr provider list

# Add or update a local custom provider catalog entry
hr provider upsert \
  --id <provider-id> \
  --name "<display name>" \
  --default-model <model-name> \
  --provider-base-url <provider-api-base-url>

# Show current LLM settings
hr llm-settings list

# Configure a realtime ASR model setting; read the key from stdin in real use
hr llm-settings add \
  --provider-id custom-asr-provider \
  --model-name realtime-asr-model \
  --display-name "Realtime ASR" \
  --endpoint-id custom_asr_realtime \
  --endpoint-name "Realtime ASR" \
  --plan-type custom \
  --protocol custom \
  --auth-type bearer \
  --model-base-url http://<asr-host>:5000 \
  --asr-realtime-url ws://<asr-host>:5002/v1/realtime \
  --supports-asr \
  --api-key-stdin

# Patch voice endpoint metadata without rebuilding the setting
hr llm-settings update <setting-id> \
  --asr-realtime-url ws://<asr-host>:5002/v1/realtime \
  --supports-asr \
  --no-supports-llm

# Show or switch the current Voice Agent runtime selection
hr voice show
hr voice configure \
  --recognition-mode asr \
  --asr-setting-id <asr-setting-id> \
  --tts-setting-id <tts-setting-id> \
  --llm-setting-id <llm-setting-id> \
  --tts-output-channel final \
  --tts-output-channel commentary

Do not configure an LLM-only model as ASR. Realtime ASR requires a separate supports_asr setting that points at a realtime-capable endpoint. Batch ASR remains a separate setting without a native realtime URL.

# Run statistics
hr stats

# Execution trace
hr trace <run_id>

For an authorized instruction to an active actor, read GET /api/runs/:id/actors, then use POST /api/runs/:id/commands with the current expected_round_id and a command containing the actual actor_id, expected_state_token, a stable idempotency_key, and the workflow's typed payload. Authenticate using the existing private x-homerail-dag-token configuration. Inspect GET /api/runs/:id/commands and the actor's output to distinguish queued, applied and completed delivery. The Manager tool send_dag_actor_command is an alternative when available. Preserve the same key and payload when reconciling an uncertain submission.

Legacy hr inject is unsupported and returns HTTP 409 / CLI exit 1 without delivering an instruction. See docs/api/dag-live-commands.md in the HomeRail source tree for the tracked request format.

Asset Discovery

The CLI sends the template path to the TS Manager API. Public examples use .yaml.template files so users can copy them before adding local provider profiles.

To discover available templates:

hr templates list

To inspect a template's structure, read the YAML file directly from assets/orchestrations/ in the repository.

Use assets/orchestrations/local-harness-cli-deploy-diagnosis.yaml.template for a single-node, read-only local harness diagnosis run that clones fresh source, tries the CLI deployment path on an isolated non-default Manager port, and creates a deployment-blocker or coverage-blocker issue only on failure.

Workflow authoring

Use homerail-dag-ops and its pattern reference for authoring. Inspect the live hr dag schema, validate before syncing, and use the current WorkflowSpec api_version / kind / metadata / spec envelope with explicit edges and terminal outcomes. Existing legacy templates may still execute, but do not copy their old implicit-terminal or unbounded-feedback shape into a new workflow. Model selection belongs in database LLM settings and runtime profiles.

MCP Tools Available to DAG Agents

Each DAG agent receives these tools automatically:

Tool	Purpose
handoff(port, content)	Must be called when finished; hands off to downstream nodes
send_message(to_node, content)	Send a message to another node in the graph
receive_message(timeout?)	Block until a message arrives
get_graph_context()	Inspect current position in the DAG graph