Command Reference

Install:

npm install -g @orgloop/cli

Commands Overview

Command	Description
orgloop init	Scaffold a new project
orgloop add	Add connectors, transforms, loggers, or routes
orgloop validate	Validate configuration files and references
orgloop env	Check environment variable configuration
orgloop doctor	Full environment health check
orgloop plan	Preview changes (Terraform-style diff)
orgloop routes	Visualize the routing topology
orgloop start	Start the runtime
orgloop status	Show runtime status and recent events
orgloop logs	Tail or query the event log
orgloop test	Inject a test event and trace its path
orgloop stop	Stop the current module (or daemon if last module)
orgloop shutdown	Stop the daemon and all modules unconditionally
orgloop hook	Forward hook events to the running engine
orgloop inspect	Deep-dive into a source, actor, or route
orgloop install-service	Generate a platform service file
orgloop service	Manage the installed service
orgloop version	Print version info

Global Flags

Available on all commands:

Flag	Short	Description
--config <path>	-c	Path to orgloop.yaml (default: ./orgloop.yaml)
--json		Machine-readable JSON output
--no-interactive		Disable interactive prompts
--verbose	-v	Verbose output
--help	-h	Show help

Configuration Resolution Order

1. CLI flags (highest priority)
2. Environment variables (ORGLOOP_*)
3. orgloop.yaml in current directory
4. ~/.orgloop/config.yaml (user defaults)

---

init

Scaffold a new OrgLoop project.

orgloop init [options]

Flag	Description
--name <name>	Project name
--connectors <list>	Comma-separated connector names (e.g., github,linear,openclaw)
--no-interactive	Skip all prompts, use defaults and flags

Interactive mode

$ orgloop init

? Project name: my-org
? Description: Engineering organization event routing
? Which connectors? (space to select)
  * GitHub
  * Linear
  * OpenClaw
  * Claude Code
    Webhook (generic)

Created:
  orgloop.yaml
  connectors/github.yaml
  connectors/linear.yaml
  connectors/openclaw.yaml
  connectors/claude-code.yaml
  routes/example.yaml
  loggers/default.yaml
  transforms/transforms.yaml
  sops/example.md

Next: run `npm install` to install dependencies, then `orgloop doctor` to check your environment.

If Claude Code is selected, init offers to install the OrgLoop stop hook into your Claude Code settings (global or project scope).

Non-interactive mode

orgloop init --name my-org --connectors github,linear,openclaw --no-interactive

---

add

Scaffold new components.

add connector

orgloop add connector <name> [options]

Flag	Description
--type <source|actor>	Connector type

orgloop add connector jira
orgloop add connector my-custom --type source

add transform

orgloop add transform <name> [options]

Flag	Description
--type <script|package>	Transform type

orgloop add transform my-filter --type script     # Creates a bash script
orgloop add transform my-enricher --type package   # Creates a TypeScript package

Script transforms: exit code 0 = pass, exit code 78 = drop.

add logger

orgloop add logger <name>

orgloop add logger datadog

add route

orgloop add route <name> [options]

Flag	Description
--source <id>	Source connector ID
--actor <id>	Actor connector ID

orgloop add route my-route --source github --actor engineering

---

validate

Validate configuration files and all references.

orgloop validate

$ orgloop validate

  ✓ orgloop.yaml                  valid project manifest
  ✓ connectors/github.yaml        valid source definition
  ✓ connectors/openclaw.yaml      valid actor definition
  ✗ routes/engineering.yaml — error at routes[0].transforms[1]:
      Transform "my-filter" not found.
  ✓ loggers/default.yaml          valid logger group

1 error, 0 warnings

What gets validated:

• YAML syntax
• Schema conformance (JSON Schema via AJV)
• Reference integrity — routes reference existing sources, actors, transforms
• Connector config completeness (required fields present)
• Transform script existence and permissions (executable bit)
• Launch prompt file existence (routes with with.prompt_file)
• Environment variable references

---

env

Check environment variable configuration. Scans all YAML files for ${VAR_NAME} references and shows which are set and which are missing.

orgloop env [check] [options]

$ orgloop env

Environment Variables:

  ✓ GITHUB_TOKEN             connectors/github.yaml
  ✗ LINEAR_API_KEY           connectors/linear.yaml
    → Linear personal API key
    → https://linear.app/settings/api
  ✓ OPENCLAW_WEBHOOK_TOKEN   connectors/openclaw.yaml

2 of 3 variables set. 1 missing.

When connector setup metadata is available, missing variables show a description and a help URL for creating the credential.

env check

Strict mode for CI. Exits with code 1 if any required variable is missing.

orgloop env check

Machine-readable output

orgloop env --json

---

doctor

Comprehensive environment health check. Goes beyond env to validate credentials against live APIs, detect running services, check config validity, and verify the route graph.

orgloop doctor [options]

Flag	Description
--json	Machine-readable JSON output (stable interface for external tools)

$ orgloop doctor

OrgLoop Doctor — my-org

  Packages:
    ✓ @orgloop/connector-github (1.2.0)
    ✓ @orgloop/connector-openclaw (1.0.3)
    ✗ @orgloop/connector-claude-code — not installed
      Fix: npm install @orgloop/connector-claude-code

  Services:
    ✓ OpenClaw running at localhost:18789 (v2.1.0)

  Credentials:
    ✓ GITHUB_TOKEN — valid (user: @alice, scopes: repo, read:org)
    ✗ LINEAR_API_KEY — not set
      → Linear personal API key
      → https://linear.app/settings/api

  Hooks:
    ✓ Claude Code stop hook — installed (global)

  Config:
    ✓ orgloop.yaml — valid
    ✓ 3 routes, 2 sources, 1 actor — all references resolve

  1 package missing, 1 credential missing.
  System will run in degraded mode.

JSON output

$ orgloop doctor --json
{
  "status": "degraded",
  "checks": [
    { "category": "package", "name": "@orgloop/connector-github", "status": "ok", "version": "1.2.0" },
    { "category": "service", "name": "openclaw", "status": "ok", "version": "2.1.0" },
    { "category": "credential", "name": "GITHUB_TOKEN", "status": "ok", "identity": "@alice" },
    { "category": "credential", "name": "LINEAR_API_KEY", "status": "missing",
      "help_url": "https://linear.app/settings/api" }
  ]
}

---

plan

Preview what will change before starting the runtime. Terraform-style diff.

orgloop plan

$ orgloop plan

OrgLoop Plan — my-org

  Sources:
    + github          (new — poll every 5m)
    + linear          (new — poll every 5m)
    ~ claude-code     (changed — secret added)

  Actors:
    = engineering     (unchanged)

  Routes:
    + github-pr-review          (new)
    + github-ci-failure         (new)
    + linear-to-engineering     (new)
    + claude-code-to-supervisor (new)

  Transforms:
    + drop-bot-noise            (new — package)

  Loggers:
    = file-log                  (unchanged)
    + console-log               (new)

Plan: 7 to add, 1 to change, 0 to remove.

Run `orgloop start` to execute this plan.

Symbols:

Symbol	Meaning
+	New — will be created
~	Changed — will be updated
=	Unchanged — already running
-	Removed — will be stopped

Plan compares your YAML config against the last running state (stored in ~/.orgloop/state.json). On first run, everything shows as + new.

---

routes

Visualize the routing topology as an ASCII graph.

orgloop routes [options]

Flag	Description
--json	Machine-readable JSON output

$ orgloop routes

OrgLoop Routes — my-org

  github ──▶ github-pr-review ──▶ engineering
                └─ filter: resource.changed, provenance.platform_event: pull_request.review_submitted
                └─ transform: drop-bot-noise → dedup

  linear ──▶ linear-to-engineering ──▶ engineering
                └─ filter: resource.changed
                └─ transform: dedup

  claude-code ──▶ claude-code-supervisor ──▶ engineering
                └─ filter: actor.stopped

5 routes, 0 warnings

Shows sources, routes with filter criteria and transform chains, and target actors. Highlights unrouted sources and unreachable actors as warnings.

---

start

Start the runtime. Events begin flowing.

Internally, start creates a Runtime instance, loads your project config, and starts an HTTP control API. The control API port is written to ~/.orgloop/runtime.port so that other commands (status, stop) can communicate with the running runtime.

orgloop start [options]

Flag	Description
--daemon	Run as background daemon
--supervised	Enable supervisor for auto-restart on crash (requires --daemon)
--force	Skip doctor pre-flight checks

Foreground (development)

$ orgloop start

  ✓ Source github — polling started (every 5m)
  ✓ Source linear — polling started (every 5m)
  ✓ Source claude-code — hook listener started
  ✓ Actor engineering — ready
  ✓ Route github-pr-review — active
  ✓ Route linear-to-engineering — active
  ✓ Route claude-code-to-supervisor — active
  ✓ Logger file-log — configured
  ✓ Logger console-log — configured

OrgLoop is running. PID: 42891
Logs: orgloop logs | Status: orgloop status | Stop: orgloop stop

Press Ctrl+C to stop in foreground mode.

Daemon mode (production)

orgloop start --daemon
# PID written to ~/.orgloop/orgloop.pid
# Control API port written to ~/.orgloop/runtime.port

# Supervised daemon (auto-restarts on crash)
orgloop start --daemon --supervised

One long-running process manages all source polling internally. Poll intervals are declared in YAML — no external schedulers, no separate LaunchAgents, no cron jobs.

Supervised daemon mode (production)

orgloop start --daemon --supervised

Adds a supervisor process that automatically restarts the runtime on crash. Exponential backoff with crash loop detection (max 10 restarts in 5 minutes). Recommended for production deployments.

Pre-flight validation

Start checks environment variables before starting. If any are missing, it fails fast with actionable guidance:

Environment Variables:

  ✓ GITHUB_REPO
  ✗ GITHUB_TOKEN             connectors/github.yaml
    → GitHub personal access token (repo scope)
    → https://github.com/settings/tokens/new?scopes=repo,read:org

1 variable missing — run `orgloop env` for details.

---

status

Show runtime status and recent events. Queries the running runtime’s control API. Falls back to PID-based status if the control API is not reachable.

orgloop status [options]

Flag	Description
--json	Machine-readable JSON output

$ orgloop status

OrgLoop Runtime
  Status: running (PID 42891)
  Uptime: 3h 22m
  Control API: http://127.0.0.1:4800

  Sources: 3 | Actors: 1 | Routes: 4

  SOURCE           TYPE      HEALTH
  github           poll      healthy
  linear           poll      healthy
  claude-code      hook      —

Recent Events (last 5):
  TIME          SOURCE    TYPE              ROUTE                      STATUS
  20:47:12      github    resource.changed  github-pr-review           delivered
  20:47:12      github    resource.changed  github-pr-review           dropped (bot)
  20:42:08      linear    resource.changed  linear-to-engineering      delivered
  20:18:33      cc        actor.stopped     claude-code-to-supervisor  delivered
  20:15:01      github    resource.changed  github-pr-review           delivered

---

logs

Tail or query the event log.

orgloop logs [options]

Flag	Description
--source <id>	Filter by source connector ID
--route <name>	Filter by route name
--result <result>	Filter by result (drop, deliver, error)
--since <duration>	Time window (e.g., 2h, 30m, 1d)
--event <id>	Trace a specific event by ID
--json	JSON output
--no-follow	Do not tail (print matches and exit)

Examples

# Tail all logs (follows new entries)
orgloop logs

# Filter by source
orgloop logs --source github

# Filter by route
orgloop logs --route github-pr-review

# Historical query (last 2 hours, resource.changed only)
orgloop logs --since 2h --source github

# Show only dropped events
orgloop logs --result drop

# Trace a specific event end-to-end
orgloop logs --event evt_abc123

# Query mode (do not follow, just print)
orgloop logs --no-follow --source linear --since 1h

# Machine-readable output
orgloop logs --json --no-follow

Log entries capture every phase of the pipeline:

{"ts":"...","phase":"source","source":"github","event_id":"evt_abc","event_type":"resource.changed"}
{"ts":"...","phase":"transform","transform":"drop-bot-noise","event_id":"evt_abc","result":"pass"}
{"ts":"...","phase":"route","event_id":"evt_abc","matched":"github-pr-review"}
{"ts":"...","phase":"deliver","event_id":"evt_abc","target":"engineering","status":"delivered"}

---

test

Inject a test event and trace its path through the pipeline.

orgloop test [file] [options]

Flag	Description
--dry-run	Trace the event path without actual delivery
--generate <connector>	Generate a sample event for a connector
-	Read event from stdin

Inject from a file

$ orgloop test event.json

Injecting test event: resource.changed (source: github)

  ✓ Transform: drop-bot-noise — PASS (2ms)
  ✓ Transform: dedup — PASS (1ms)
  ✓ Route match: github-pr-review
  ✓ Delivery: engineering — 200 OK (89ms)

Event evt_test_001 traced successfully through 1 route.

Dry run

orgloop test event.json --dry-run

Traces the event through transforms and route matching without delivering to actors.

Generate a sample event

# Generate and print a sample event for a connector
orgloop test --generate github

# Generate and immediately test the pipeline
orgloop test --generate github | orgloop test -

Inject from stdin

echo '{"type":"resource.changed","source":"github","payload":{}}' | orgloop test -

---

stop

Stop the current module. Module-aware — if multiple modules share a daemon, only the current directory’s module is unloaded. If it is the last module, the daemon shuts down entirely.

orgloop stop [options]

Flag	Description
--force	Force kill with SIGKILL
--all	Stop the daemon and all modules (alias for orgloop shutdown)

# Single module running:
$ orgloop stop
Module "engineering-org" is the last module. Shutting down daemon.
Stopping OrgLoop daemon (PID 42891)...
  ✓ Stopped.

# Multiple modules running:
$ orgloop stop
Unloading module "engineering-org"...
Module "engineering-org" stopped. Daemon continues with 1 module(s).

Graceful shutdown: flushes log buffers, persists source checkpoints, waits for in-flight deliveries (with timeout), then exits. If the process does not exit within 10 seconds, it is force-killed with SIGKILL.

---

shutdown

Stop the daemon and all loaded modules unconditionally. Unlike stop, which is module-aware, shutdown always takes down the entire daemon.

orgloop shutdown [options]

Flag	Description
--force	Force kill with SIGKILL

$ orgloop shutdown

Stopping OrgLoop daemon (PID 42891)...
Requesting graceful shutdown via control API...
  ✓ Stopped.

---

hook

Forward hook events from external tools to the running OrgLoop engine.

orgloop hook <hook-type> [options]

claude-code-stop

Forward a Claude Code stop hook event.

orgloop hook claude-code-stop

Reads hook event data from stdin and POSTs it to the running engine’s webhook endpoint. Used by Claude Code’s post-exit hooks to forward session completion events into OrgLoop’s pipeline.

The engine must be running with a claude-code source registered.

---

inspect

Deep-dive into a specific source, actor, or route.

orgloop inspect <type> <name>

Inspect a source

$ orgloop inspect source github

Name:       github
Type:       poll (every 5m)
Connector:  @orgloop/connector-github
Config:     repo=my-org/my-repo
Emits:      resource.changed
Checkpoint: 2026-02-08T20:47:00Z
Routes:     github-pr-review, github-ci-failure
Events:     47 (24h), 312 (7d)

Inspect a route

$ orgloop inspect route github-pr-review

Name:       github-pr-review
Source:     github → [drop-bot-noise, dedup] → engineering
Prompt:     ./sops/pr-review.md
Matched:    45 (24h)
Dropped:    2 (24h) — all by drop-bot-noise
Errors:     0
Last event: 3 min ago (evt_abc123)

Shows configuration, event statistics, connected components, and recent activity.

---

install-service

Generate a platform service file to run OrgLoop as a system service.

orgloop install-service [options]

Flag	Description
--launchd	macOS LaunchAgent plist
--systemd	Linux systemd user service
--docker	Dockerfile + docker-compose.yaml

Auto-detect platform

$ orgloop install-service

Detected platform: macOS (launchd)
Generated: ~/Library/LaunchAgents/com.orgloop.daemon.plist
  KeepAlive: true
  WorkingDirectory: ~/.orgloop
  Config: ~/.orgloop/orgloop.yaml

To activate:
  launchctl load ~/Library/LaunchAgents/com.orgloop.daemon.plist

Explicit platform

orgloop install-service --systemd    # Linux
orgloop install-service --launchd    # macOS
orgloop install-service --docker     # Docker

The generated service keeps OrgLoop alive across reboots and restarts on crash.

---

service

Manage the installed system service. Thin wrappers around platform tools (launchctl, systemctl).

orgloop service <action>

Action	Description
start	Start the OrgLoop service
stop	Stop the service
status	Show service status
logs	View service logs

orgloop service start
orgloop service stop
orgloop service status
orgloop service logs

---

version

Print version information.

orgloop version

$ orgloop version
@orgloop/cli 1.0.0

---

Built-in REST API

The runtime includes an HTTP server (default port 4800, configurable via ORGLOOP_PORT) that starts automatically with orgloop start. It serves three route families.

Observability — GET /api/*

Endpoint	Description
GET /api/status	Runtime health, uptime, PID, per-module status, per-source detail
GET /api/routes	All routes with fire counts and last-fired timestamps
GET /api/events	Recent events from ring buffer. Query params: from, to, source, route, limit
GET /api/sources	Per-source connector detail (type, health, event count, poll interval)
GET /api/metrics	Prometheus-format metrics (requires ORGLOOP_METRICS_PORT env var)

Control — POST /control/*

Endpoint	Description
GET /control/status	Runtime status snapshot
POST /control/module/load	Load a new module: { name, config }
POST /control/module/unload	Unload a module: { name }
POST /control/module/reload	Reload a module: { name }
GET /control/module/list	List all loaded modules
GET /control/module/status/:name	Status of a specific module
POST /control/shutdown	Graceful runtime shutdown

Webhooks — POST /webhook/*

Endpoint	Description
POST /webhook/:sourceId	Receive webhook events for hook-based sources (coding-agent, webhook)

The HTTP server binds to 127.0.0.1 (localhost only). CLI commands like orgloop status and orgloop stop communicate with the running runtime via these endpoints.