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

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, 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 (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 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 receives -i - and records the hyphen as the input source.
2. Payload Routing – app/main.py calls load_payload, which identifies the special path and invokes load_stdin.
3. Stream Validation – 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 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:

cat alert.json | opensre investigate -i -

Echo Inline JSON

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

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:

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 (load_stdin, lines 53‑59) and 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 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, but the STDIN handling logic in 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.

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.

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