Skip to content

Overlord CLI

Jump to bottom
Jason L. West edited this page Feb 10, 2026 · 6 revisions

Overlord CLI Reference

The Overlord provides a CLI for meta-orchestration tasks across your project ecosystem. All commands are accessed via nebulus-atom overlord <command>.

Configuration

overlord config

Display the loaded Overlord configuration.

nebulus-atom overlord config

Output:

  • Projects discovered
  • Dependency relationships
  • Test commands
  • Build/check scripts

Options:

  • --validate - Validate circular dependencies and missing projects

Discovery

overlord discover

Scan the workspace for overlord.yml files and discover all projects.

nebulus-atom overlord discover [--path /path/to/workspace]

Options:

  • --path PATH - Workspace root (default: parent of current directory)
  • --save - Save discovered projects to registry

Output:

  • List of discovered projects
  • Paths to their overlord.yml files
  • Quick validation status

Status & Scanning

overlord status

Show the current state of all projects: git status, branch, test health.

nebulus-atom overlord status [--projects PROJECT ...]

Options:

  • --projects PROJECT [PROJECT ...] - Filter to specific projects (default: all)
  • --format {table,json} - Output format (default: table)

Output:

  • Git status (clean, dirty, ahead, behind)
  • Active branch
  • Test status (passed, failed, not run)
  • Last commit timestamp

overlord scan

Deep scan of all projects: git state, test execution, health check.

nebulus-atom overlord scan [--projects PROJECT ...] [--run-tests]

Options:

  • --projects PROJECT [PROJECT ...] - Filter to specific projects
  • --run-tests - Actually run test suites (slow, default: skip)
  • --save - Save scan results to memory

Output:

  • Detailed git state
  • Test results (if run)
  • Uncommitted changes count
  • Unpushed commits count

Dependency Graph

overlord graph

Visualize and query the project dependency graph.

# Show full dependency graph (ASCII tree)
nebulus-atom overlord graph

# Show dependencies of a specific project
nebulus-atom overlord graph --project nebulus-core

# Show what depends on a project
nebulus-atom overlord graph --project nebulus-core --mode dependents

# Show affected projects if nebulus-core changes
nebulus-atom overlord graph --project nebulus-core --mode affected

# Extract subgraph for specific projects
nebulus-atom overlord graph --subgraph nebulus-core,nebulus-prime

Modes:

  • full - Complete dependency graph (default)
  • upstream - What this project depends on
  • downstream - What depends on this project (dependents)
  • affected - All projects affected by a change to this project

Options:

  • --project PROJECT - Focus on a specific project
  • --mode {full,upstream,downstream,affected} - Graph mode
  • --subgraph PROJECT,PROJECT,... - Extract subgraph
  • --format {tree,json} - Output format (default: tree)

Output:

  • ASCII dependency tree
  • Dependency order (topological sort)
  • Cycle warnings (if any)

Action Scope

overlord scope

Evaluate the blast radius and autonomy suitability of a proposed change.

nebulus-atom overlord scope --project nebulus-atom --type local

Change Types:

  • local - Changes only affect the project itself
  • upstream - Changes to dependencies (affects downstream)
  • downstream - Changes to dependents (may need upstream updates)
  • cross_cutting - Changes affect multiple unrelated projects

Options:

  • --project PROJECT - Project being changed (required)
  • --type {local,upstream,downstream,cross_cutting} - Change type (required)
  • --targets PROJECT [PROJECT ...] - Specific affected projects (optional)

Output:

  • Scope category (narrow, moderate, broad)
  • Affected project list
  • Autonomy recommendation (auto-dispatch vs. human review)
  • Confidence score
  • Suggested reviewers

Memory

overlord memory remember

Store a cross-project observation or learning.

nebulus-atom overlord memory remember \
  --project nebulus-core \
  --observation "After changing LLMClient, always rebuild nebulus-prime Docker image" \
  --category gotcha \
  --confidence high

Options:

  • --project PROJECT - Associated project (can specify multiple)
  • --observation TEXT - The observation to remember (required)
  • --category {pattern,gotcha,decision,performance,security} - Observation type
  • --confidence {low,medium,high} - Confidence level (default: medium)

overlord memory search

Search stored observations by keyword or project.

# Search by keyword
nebulus-atom overlord memory search "docker build"

# Search by project
nebulus-atom overlord memory search --project nebulus-prime

# Search by category
nebulus-atom overlord memory search --category gotcha

Options:

  • --project PROJECT - Filter by project
  • --category CATEGORY - Filter by category
  • --limit N - Max results (default: 10)

Output:

  • Matching observations with timestamps
  • Associated projects
  • Confidence levels
  • Categories

overlord memory forget

Remove an observation by ID.

nebulus-atom overlord memory forget <observation-id>

overlord memory prune

Clean up stale observations (older than threshold, low confidence).

nebulus-atom overlord memory prune --days 90 --min-confidence medium

Options:

  • --days N - Remove observations older than N days (default: 180)
  • --min-confidence {low,medium,high} - Remove below this confidence (default: low)
  • --dry-run - Show what would be deleted without deleting

Daemon

overlord daemon

Manage the background daemon lifecycle — start, stop, restart, and check status. Uses a PID file at ~/.atom/overlord/daemon.pid for reliable process discovery.

# Start the daemon
nebulus-atom overlord daemon start

# Check if daemon is running
nebulus-atom overlord daemon status

# Stop a running daemon (sends SIGTERM, waits up to 5s)
nebulus-atom overlord daemon stop

# Restart (stop + start)
nebulus-atom overlord daemon restart

Actions:

Action Description
start Launch the daemon. Auto-loads .env, configures logging, refuses if already running.
status Show running/stopped state and PID. Detects stale PID files.
stop Send SIGTERM to running daemon, wait for clean exit.
restart Stop (if running) then start.

What start does on launch:

  1. Auto-loads .env from the current working directory
  2. Prints environment variable detection status (SLACK_BOT_TOKEN, etc.)
  3. Configures structured logging to ~/.atom/overlord/daemon.log
  4. Loads the Overlord registry from overlord.yml
  5. Displays scheduled tasks (or "No scheduled tasks configured — scheduler will idle")
  6. Starts the Slack bot (if tokens set) and waits for Socket Mode to connect
  7. Reconciles pending proposals — reads Slack threads for any approve/deny replies missed while offline, updates proposal states, and notifies in threads
  8. Starts the scheduler loop and cleanup loop

What the daemon does:

  • Connects to Slack via Socket Mode (if tokens set)
  • Runs scheduled tasks via croniter (scan, test-all, clean-stale-branches)
  • Routes detections through the ProposalManager for approval
  • Sends daily digest notifications

Environment variables:

  • SLACK_BOT_TOKEN - Slack bot token
  • SLACK_APP_TOKEN - Slack app token (Socket Mode)
  • SLACK_CHANNEL_ID - Channel for Overlord messages
  • LOG_LEVEL - Logging level (default: INFO)

Schedule configuration (in overlord.yml):

schedule:
  scan: "0 * * * *"           # Hourly health check
  test-all: "0 2 * * *"       # Nightly test sweep
  clean-stale-branches:
    cron: "0 3 * * 0"         # Weekly branch cleanup
    enabled: true

notifications:
  urgent_enabled: true
  digest_enabled: true
  digest_cron: "0 8 * * *"    # 8 AM UTC daily

Slack Commands (Phase 3)

When the daemon is running, the Overlord listens for @atom mentions in the configured Slack channel. Messages are routed through the SlackCommandRouter to the Phase 2 stack.

status [project]

Show ecosystem health or a single project's status.

@atom status           # All projects
@atom status core      # Single project

Output: Git branch, clean/dirty status, ahead/behind counts, test health, issues.

scan [project]

Deep scan with proactive detection (stale branches, ahead-of-main, failing tests).

@atom scan             # All projects
@atom scan prime       # Single project

Output: Detailed scan results plus any detections found, filtered by autonomy level.

merge <project> <source> to <target>

Dispatch a merge operation. Creates a proposal if approval is required under the current autonomy level.

@atom merge core develop to main

Flow:

  1. TaskParser builds a DispatchPlan with scope analysis
  2. If autonomy requires approval → creates a proposal, posts to Slack
  3. Reply "approve" or "deny" in the thread to control execution
  4. If approved → executes via DispatchEngine, reports result

release <project> <version>

Coordinated release workflow via ReleaseCoordinator.

@atom release core v0.3.0

Flow: Validates release spec → creates proposal → on approval, executes release steps (merge, tag, push) in dependency order.

autonomy [level]

Show or change the global autonomy level.

@atom autonomy             # Show current level and summary
@atom autonomy proactive   # Change to proactive

Levels: cautious (requires approval for all actions), proactive (auto-executes low-risk), scheduled (auto-executes on schedule).

memory <query>

Search cross-project observations.

@atom memory docker build issues

Output: Matching observations with timestamps, projects, categories, and confidence levels.

approve <proposal-id> / deny <proposal-id>

Approve or deny a pending proposal directly by ID (alternative to thread replies).

@atom approve abc123
@atom deny abc123

help

List all available commands with descriptions.

@atom help

Proposal Thread Replies

When a proposal is posted to Slack, you can reply directly in the thread:

approve    # Approve and execute the proposal
deny       # Deny the proposal

Proposals auto-expire after 30 minutes if no action is taken.

Proposal message format:

Proposal: Merge Core develop to main

Scope: core | affects remote | estimated: low
Autonomy: cautious (requires approval)

Reply "approve" or "deny" in this thread.
Auto-expires in 30 minutes.

Examples

Check health of all projects:

nebulus-atom overlord status

Find what depends on nebulus-core:

nebulus-atom overlord graph --project nebulus-core --mode downstream

Evaluate scope of changing nebulus-atom:

nebulus-atom overlord scope --project nebulus-atom --type local

Remember a cross-project gotcha:

nebulus-atom overlord memory remember \
  --project nebulus-prime,nebulus-edge \
  --observation "TabbyAPI and MLX server have different streaming response formats" \
  --category gotcha \
  --confidence high

Search for Docker-related observations:

nebulus-atom overlord memory search "docker"

Start the daemon and use Slack commands:

# Terminal
nebulus-atom overlord daemon start

# In Slack (#nebulus-ops)
@atom status
@atom scan core
@atom merge core develop to main
# → Proposal posted, reply "approve" in thread
@atom autonomy proactive

Related Pages

Getting Started

Core System

Nebulus Swarm

Overlord Phase 3

Operations

Clone this wiki locally