LoopX CLI Commands: Complete Reference and Usage Guide

The LoopX CLI provides a single entry-point binary with global options and over 50 sub-commands organized into logical groups for operators, maintainers, and automation workflows.

The LoopX framework, maintained in the huangruiteng/loopx repository, exposes its agent coordination and registry management capabilities through a comprehensive command-line interface. Understanding the available LoopX CLI commands and their usage patterns is essential for operating goal-driven workflows, managing project state, and maintaining the shared runtime registry.

Global Options and Entry Point

The LoopX CLI binary accepts three global flags that must appear before any subcommand. These definitions reside in [loopx/help_surface.py](https://github.com/huangruiteng/loopx/blob/main/loopx/help_surface.py) (lines 8-10) and are parsed in [loopx/cli.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) (lines 95-99):

• --registry <PATH>: Path to a project-local registry (defaults to ~/.local/share/loopx/registry)
• --runtime-root <PATH>: Override the common runtime root for the registry
• --format markdown|json: Output format for commands emitting structured data

These options configure the runtime environment before command dispatch:

loopx --registry /custom/path --format json status

Command Architecture and Patterns

LoopX implements a hierarchical command structure defined in the COMMAND_GROUPS catalog within [help_surface.py](https://github.com/huangruiteng/loopx/blob/main/loopx/help_surface.py) (lines 13-170). The [cli.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) entry point registers each command via register_*_commands calls (lines 101-134) and dispatches to handlers implemented in [cli_commands.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands.py).

The general usage pattern follows this sequence:

loopx [global options] <command> [command-options]

Output formatting logic, including automatic JSON enforcement for specific commands like quota should-run, is handled by the resolve_global_output_format function in [cli.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) (lines 81-85).

Command Groups Reference

Getting Started Commands

These initialization and verification commands prepare the environment for agent operations:

• loopx doctor: Verifies installation health, PATH configuration, release snapshots, and skill integrity.
• loopx slash-commands --install: Refreshes host slash-command skill files for chat integration.
• loopx preset list: Displays beginner-safe and advanced start packets for new projects.
• loopx ready-score --goal-id <id>: Scores installation status, quotas, and readiness without writing badges.
• loopx start-goal: Previews the shell fallback for initiating goals with flags like --guided and --project.
• loopx agent-onboard: Generates host-loop activation packets for specific agent types (e.g., --agent-type codex-cli).
• /loopx and /loopx <goal>: Chat-native commands for inspecting LoopX state and starting long-running goals.

Daily Operator Commands

Core workflow commands for active goal management, diagnostics, and task tracking:

• loopx status: Displays current goals, gates, attention queues, and recommended next actions.
• loopx diagnose --goal-id <id>: Builds compact evidence packets when troubleshooting unexpected agent behavior.
• loopx todo: Manages task lists with subcommands including add, claim, complete, update, and archive.
• loopx task-lease: Handles lease lifecycle management with operations for acquire, renew, transfer, and release.
• loopx quota should-run: Returns JSON-formatted decisions on whether the next agent turn should execute.
• loopx evidence-log: Reads thin public-safe ledgers using filters like --goal-id, --agent-id, and --thin.
• loopx review-packet: Renders hand-off or review packets with evidence-log reads for specific goals.

Setup and Automation

Project bootstrap and maintenance automation commands:

• loopx bootstrap or loopx connect: Creates or connects project-local state directories and registries.
• loopx new-project-prompt: Generates copy-paste connection prompts for agent onboarding workflows.
• loopx codex-cli-bootstrap-message: Produces Codex CLI TUI setup messages for visible agent attachment.
• loopx upgrade-plan: Plans default heartbeat upgrade propagation across the project.
• loopx update: Executes no-clone update paths with dry-run and execute modes.
• loopx project-skill: Installs, inspects, or removes release-owned skills via install and remove subcommands.

Maintainer and Advanced Commands

Registry management, verification, and administrative tooling:

• loopx check: Runs contract and public/private boundary checks against project policy.
• loopx registry: Inspects registered goals, adapters, and runtime state.
• loopx sync-global: Merges project state into the shared registry.
• loopx retire-global-goal: Safely retires orphaned global goal routes.
• loopx register-agent: Registers automation agents with the system registry.
• loopx version: Prints the installed LoopX version sourced from [__init__.py](https://github.com/huangruiteng/loopx/blob/main/loopx/__init__.py).
• loopx commands: Displays the grouped command reference in markdown format.
• loopx change-quality: Qualifies final diffs against project quality policies.
• loopx integration-branch: Detects branch drift and rebuilds local integration branches.
• loopx multi-agent: Launches visible role-scoped Codex TUI agents via the launch subcommand.
• loopx canary: Plans and runs catalog-informed smoke profiles.
• loopx benchmark: Executes fixture-only benchmark runner skeletons.

Practical Usage Examples

Verify installation and system health:

loopx doctor

Check current operational status with JSON output:

loopx --format json status

Initialize a new project with a custom registry location:

loopx bootstrap --registry /var/lib/loopx/registry --project .

Add a task and claim the lease:

loopx todo add --title "Update dependencies" --owner alice
loopx todo claim --id 7

Run quota validation for automated decision-making:

loopx quota should-run

Generate diagnostic evidence for a specific goal:

loopx diagnose --goal-id 42

Launch a multi-agent visible TUI session:

loopx multi-agent launch --agents codex-cli,assistant

Summary

• LoopX CLI commands are organized into logical groups including Getting Started, Daily Operations, Setup/Automation, and Maintainer tools.
• Global options (--registry, --runtime-root, --format) must precede subcommands and are parsed in [cli.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) (lines 95-99).
• The command catalog COMMAND_GROUPS is defined in [help_surface.py](https://github.com/huangruiteng/loopx/blob/main/loopx/help_surface.py) (lines 13-170), covering chat commands, operator workflows, and administrative functions.
• Output defaults to markdown but supports JSON via --format json; certain commands like quota should-run enforce JSON automatically through resolve_global_output_format ([cli.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) lines 81-85).
• Command handlers are implemented in [cli_commands.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands.py), while default paths are resolved via [paths.py](https://github.com/huangruiteng/loopx/blob/main/loopx/paths.py).

Frequently Asked Questions

What is the basic syntax for LoopX CLI commands?

The LoopX CLI follows the pattern loopx [global options] <command> [command-options]. Global flags like --registry or --format must appear before the subcommand, while command-specific options follow the command name. This structure is enforced by the argument parser defined in [loopx/cli.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) (lines 95-99).

How do I change the output format to JSON?

Use the --format json global option before any subcommand, such as loopx --format json status. Certain commands like quota should-run automatically enforce JSON output regardless of the global flag via the resolve_global_output_format logic in [cli.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) (lines 81-85).

Where are the LoopX CLI commands defined in the source code?

The canonical command catalogue lives in the COMMAND_GROUPS dictionary in [loopx/help_surface.py](https://github.com/huangruiteng/loopx/blob/main/loopx/help_surface.py) (lines 13-170). Registration logic resides in [loopx/cli.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) (lines 101-134), while concrete handler implementations are located in [loopx/cli_commands.py](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands.py).

How do I install or refresh slash commands?

Run loopx slash-commands --install to refresh host slash-command skill files. This command updates the integration points for chat-based agents interacting with the LoopX runtime, ensuring the /loopx chat commands are properly registered with the host environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}