# How to Run an OpenSRE Investigation from STDIN: Complete CLI Guide

> Streamline OpenSRE investigations by running them from STDIN. Learn how to use the -i - flag with opensre investigate for seamless shell piping and automation.

- Repository: [Tracer/opensre](https://github.com/Tracer-Cloud/opensre)
- Tags: how-to-guide
- Published: 2026-04-18

---

**Use the `-i -` flag when running `opensre investigate` to read JSON alert payloads directly from standard input, enabling shell pipes, here-documents, and CI/CD automation.**

The OpenSRE framework (Tracer-Cloud/opensre) supports ingesting alert payloads via **standard input (STDIN)**, which eliminates the need for temporary files when integrating with monitoring systems or automated pipelines. This capability is implemented through a special path identifier that triggers STDIN mode in the CLI parser.

## How STDIN Detection Works in OpenSRE

When you invoke the investigation command with the `-` input path, the framework performs a TTY check to confirm data is being piped rather than requested from an interactive terminal. According to the source code in [`app/cli/payload.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/payload.py), the `load_stdin` function (lines 53‑59) first verifies that `sys.stdin.isatty()` returns **false**, then reads the entire stream using `sys.stdin.read()`.

If the stream is empty, `load_stdin` raises a descriptive error immediately. Otherwise, it passes the raw text to `parse_payload_text` for JSON deserialization before handing the resulting dictionary to the investigation runner. This validation ensures the framework fails fast on missing input rather than attempting to parse empty strings.

## Using the `-i -` Flag to Read from STDIN

The CLI argument definition in [`app/cli/args.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/args.py) (lines 21‑22) documents the `-` shortcut as the canonical way to request STDIN input. When executing `opensre investigate -i -`, the entry point in [`app/main.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/main.py) routes the request through the `load_payload` helper (lines 80‑89), which detects the hyphen path and delegates to `load_stdin` instead of file system operations.

This approach allows you to stream JSON directly into the investigation engine without writing to disk, which is particularly useful for ephemeral container environments and serverless functions.

## Step‑by‑Step Execution Flow

The complete data path from your shell to the investigation report follows this sequence:

1. **Argument Parsing** – [`app/cli/args.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/args.py) receives `-i -` and records the hyphen as the input source.
2. **Payload Routing** – [`app/main.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/main.py) calls `load_payload`, which identifies the special path and invokes `load_stdin`.
3. **Stream Validation** – [`app/cli/payload.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/payload.py) checks `isatty()` and raises an error for empty pipes.
4. **JSON Parsing** – `parse_payload_text` converts the raw stream into a Python dictionary.
5. **Investigation Dispatch** – [`app/cli/commands/general.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/commands/general.py) forwards the payload to `run_investigation_cli` for execution.
6. **Output** – Results print to stdout or the file specified by `--output`.

## Practical Code Examples

### Pipe a JSON File Directly

Redirect file contents through a pipe to avoid loading the entire document into your shell history:

```bash
cat alert.json | opensre investigate -i -

```

### Echo Inline JSON

For quick tests or single‑alert debugging, pipe a JSON string directly:

```bash
echo '{"alert_name":"High CPU","pipeline_name":"events_fact","severity":"warning"}' \
  | opensre investigate -i -

```

### Use a Here‑Document for Multi‑Line Payloads

When testing complex alert structures, shell here‑documents preserve formatting without escape characters:

```bash
opensre investigate -i - <<EOF
{
  "alert_name": "DatabaseLatency",
  "pipeline_name": "events_fact",
  "severity": "critical"
}
EOF

```

All three methods invoke the same internal logic: the CLI reads from `sys.stdin`, validates the JSON structure, and executes the investigation against the parsed payload.

## Error Handling and Edge Cases

The `load_stdin` implementation explicitly guards against empty input streams. If you accidentally run `opensre investigate -i -` in an interactive terminal without piping data, the function raises a clear error indicating that STDIN is empty. This prevents the framework from attempting to parse blank strings or hanging indefinitely waiting for input.

Additionally, because `parse_payload_text` handles the JSON deserialization, any malformed syntax errors surface immediately with standard Python JSON exceptions, allowing you to catch formatting issues before the investigation logic begins.

## Summary

- **Use `-i -`** to instruct OpenSRE to read alert payloads from standard input rather than the file system.
- **Implementation** resides in [`app/cli/payload.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/payload.py) (`load_stdin`, lines 53‑59) and [`app/main.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/main.py) (`load_payload`, lines 80‑89).
- **Validation** includes TTY detection via `sys.stdin.isatty()` and empty‑stream checks.
- **Flexibility** supports pipes, echo commands, and here‑documents for seamless automation.
- **Processing** follows the path: STDIN → `load_stdin` → `parse_payload_text` → `run_investigation_cli`.

## Frequently Asked Questions

### What happens if I run `-i -` without piping any data?

OpenSRE will raise an error immediately. The `load_stdin` function in [`app/cli/payload.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/payload.py) checks if the stream is empty after confirming `sys.stdin.isatty()` is false, and exits with a descriptive message rather than processing blank input.

### Can I use STDIN input with OpenSRE commands other than `investigate`?

The `-i` flag is defined globally in [`app/cli/args.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/args.py), but the STDIN handling logic in [`app/main.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/main.py) specifically routes to `load_stdin` when the hyphen path is detected. While the flag exists for other commands, the STDIN-to-investigation pipeline is optimized and documented for the `investigate` subcommand as implemented in [`app/cli/commands/general.py`](https://github.com/Tracer-Cloud/opensre/blob/main/app/cli/commands/general.py).

### What JSON format does OpenSRE expect from STDIN?

OpenSRE expects a valid JSON object containing alert metadata fields such as `alert_name`, `pipeline_name`, and `severity`. The `parse_payload_text` function validates this structure during ingestion, rejecting malformed JSON before the investigation begins.

### How does OpenSRE validate that STDIN contains valid JSON?

After reading the stream via `sys.stdin.read()`, the framework passes the content to `parse_payload_text`, which attempts JSON deserialization. If parsing fails, Python’s built-in JSON exception propagates to the user with line and column details, ensuring you receive immediate feedback on syntax errors without entering the investigation logic.