# CLI Contract: `convert_article_to_markdown.py`

**Feature**: `005-convert-json-markdown` | **Date**: 2026-08-21

## 1. Script Signature

```bash
python scripts/convert_article_to_markdown.py -i <input_path> [-o <output_path>]
```

## 2. Command-Line Arguments

| Flag | Long Option | Type | Required | Default | Description |
|---|---|---|:---:|---|---|
| `-i` | `--input` | String / Path | Yes | — | Path to the source JSON file containing exactly one article object. |
| `-o` | `--output` | String / Path | No | `<input_stem>.md` | Destination path for the generated Markdown file. |

## 3. Exit Codes

| Exit Code | Meaning | Standard Streams Behavior |
|:---:|---|---|
| `0` | **Success**: Article converted and Markdown written atomically. | Diagnostic info on `stderr`, clean execution. |
| `1` | **Runtime / Validation Error**: Malformed JSON, root `articles` array, missing mandatory fields (title, original URL, body), invalid selected extractor, or write failure. | Descriptive error message printed to `stderr`. Pre-existing target file unmodified. |
| `2` | **Argument Error**: Missing required `-i/--input` argument, unrecognized arguments, or invalid CLI usage. | Standard `argparse` usage and error output printed to `stderr`. |

## 4. Standard Stream Behavior

- **`stdout`**: Reserved. No Markdown text is dumped to `stdout` when generating file output.
- **`stderr`**: Receives progress/error diagnostics, e.g.:
  - `[INFO] Converted 'out/article_001.json' -> 'out/article_001.md' (extractor: trafilatura)`
  - `[ERROR] Invalid input: JSON contains batch 'articles' array. Only single article JSON files are accepted.`