# LoopX CLI Commands: Complete Reference and Usage Guide

> Master LoopX CLI commands with this comprehensive reference. Discover over 50 sub-commands for operators, maintainers, and automation. Enhance your workflow today.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: api-reference
- Published: 2026-08-07

---

**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)](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)](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:

```bash
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/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/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/cli_commands.py)](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands.py).

The general usage pattern follows this sequence:

```bash
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/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/__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:

```bash
loopx doctor

```

Check current operational status with JSON output:

```bash
loopx --format json status

```

Initialize a new project with a custom registry location:

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

```

Add a task and claim the lease:

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

```

Run quota validation for automated decision-making:

```bash
loopx quota should-run

```

Generate diagnostic evidence for a specific goal:

```bash
loopx diagnose --goal-id 42

```

Launch a multi-agent visible TUI session:

```bash
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/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/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/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/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/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)](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/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)](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)](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)](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.