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

> Master LoopX input and output formats including JSON, Markdown, Mermaid, and SVG. Control CLI data handling and presentation layer inputs with ease. Learn more!

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

---

**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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py), where parsed arguments are extracted and propagated to rendering functions. Tests in [`tests/test_cli_argument_diagnostics.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_cli_argument_diagnostics.py) verify that only these two values are accepted and that inheritance rules work correctly across sub-commands.

```bash

# Render quota check as structured JSON for downstream processing

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

```

```bash

# 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.

```bash

# Feed a Mermaid diagram and generate SVG output

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

```

```bash

# 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`](https://github.com/huangruiteng/loopx/blob/main/tests/test_loopx_turn_journal_inspection.py) validates both JSON and Markdown handling across different command contexts.

Key behavior observed in [`loopx/cli.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) | Defines argument parser, `choices=["json", "markdown"]`, and `output_format()` helper |
| [`tests/test_cli_argument_diagnostics.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_cli_argument_diagnostics.py) | Unit tests for format flag validation and precedence rules |
| [`tests/test_loopx_turn_journal_inspection.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_loopx_turn_journal_inspection.py) | Integration tests for dual-format output modes |
| [`docs/guides/getting-started.md`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) with validation in [`tests/test_cli_argument_diagnostics.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/tests/test_cli_argument_diagnostics.py) suite specifically verifies JSON handling for programmatic use cases.