LoopX Input and Output Formats: A Complete Guide to CLI Data Handling

LoopX supports json and markdown for CLI output, plus json, mermaid, and svg for presentation layer input, all controlled via --format and --input_format flags.

LoopX is an open-source CLI tool for evidence-based workflow automation. Understanding its supported input and output formats is essential for integrating it into data pipelines, documentation workflows, and automated reporting systems.

Output Formats in LoopX CLI

The command-line interface in loopx/cli.py defines a unified --format flag that controls how all sub-commands render their results.

Supported Output Options

The argument parser registers --format with choices=["json", "markdown"] via the output_format() helper function. When omitted, sub-commands use their own default preferences.

Format	Use Case	Example Command
json	Machine-readable API responses, pipeline integration	loopx --format json quota should-run
markdown	Human-readable documentation, reports	loopx --format markdown quota should-run

CLI Output Format Implementation

The format selection logic resides in loopx/cli.py, where parsed arguments are extracted and propagated to rendering functions. Tests in tests/test_cli_argument_diagnostics.py verify that only these two values are accepted and that inheritance rules work correctly across sub-commands.

# Render quota check as structured JSON for downstream processing

loopx --format json quota should-run --goal-id my-goal

# Render the same check as Markdown for documentation

loopx --format markdown quota should-run --goal-id my-goal

Input Formats for Presentation Layer

LoopX's presentation subsystem accepts additional formats through the --input_format option. These are used when rendering visual artifacts or processing structured data passed via stdin.

Supported Input Options

Format	Purpose	Typical Source
json	Structured data payloads	API responses, serialized objects
mermaid	Diagram description language	.mmd files, generated charts
svg	Raw vector graphics data	Image assets, diagram exports

Input Format Implementation

Commands that render visual artifacts (e.g., loopx present) expose --input_format to specify how incoming data should be parsed. The value propagates to the renderer for correct interpretation.

# Feed a Mermaid diagram and generate SVG output

cat diagram.mmd | loopx present --input_format mermaid --output_format svg

# Process JSON from stdin, output as Markdown

cat data.json | loopx process --format markdown

Format Precedence and Inheritance

Sub-commands inherit the global --format setting unless they explicitly override it. The test suite in tests/test_loopx_turn_journal_inspection.py validates both JSON and Markdown handling across different command contexts.

Key behavior observed in loopx/cli.py:

• Global --format acts as default for all outputs
• --input_format is command-specific and parsed separately
• Invalid choices trigger argparse validation errors before execution

File Locations and Source References

File	Role
loopx/cli.py	Defines argument parser, choices=["json", "markdown"], and output_format() helper
tests/test_cli_argument_diagnostics.py	Unit tests for format flag validation and precedence rules
tests/test_loopx_turn_journal_inspection.py	Integration tests for dual-format output modes
docs/guides/getting-started.md	User documentation for format selection

Summary

• LoopX output formats: json (machine-readable), markdown (human-readable)
• LoopX input formats: json, mermaid, svg (presentation layer only)
• Primary flags: --format for output, --input_format for presentation input
• Source implementation: loopx/cli.py with validation in tests/test_cli_argument_diagnostics.py

Frequently Asked Questions

What happens if I specify an unsupported format in LoopX?

The CLI argparse configuration rejects invalid values before execution begins. In loopx/cli.py, the --format flag uses choices=["json", "markdown"], so any other value produces a standard argparse error message listing allowed options.

Can I use different formats for input and output in the same command?

Yes. The presentation commands support independent flags: --input_format controls how stdin is parsed (e.g., mermaid), while --format or --output_format determines the rendered output. These operate on separate data paths within the CLI.

Does LoopX support CSV or YAML formats?

No. According to the source code in loopx/cli.py and the test suite, only json and markdown are registered as valid output choices. No evidence of CSV or YAML parsers exists in the argument definitions or validation tests.

Which format should I use for CI/CD pipeline integration?

Use json. It provides structured, parseable output that integrates cleanly with shell scripts, GitHub Actions, and other automation tools. The tests/test_cli_argument_diagnostics.py suite specifically verifies JSON handling for programmatic use cases.

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