# CLI Interface Contract: Deterministic Article Content Selection

**Branch**: `004-deterministic-content-selection` | **Date**: 2026-08-20 | **Spec**: [spec.md](../spec.md)

---

## 1. Command Syntax

```bash
python scripts/select_article_extractor.py <input_file> [-o OUTPUT] [--indent INDENT] [--verbose]
```

---

## 2. Arguments and Flags

| Argumento / Flag | Tipo | Obrigatório | Padrão | Descrição |
|---|---|:---:|---|---|
| `input_file` | `Path` (Posicional) | Sim | - | Caminho para o arquivo JSON contendo a coleção `articles` extraída. |
| `-o`, `--output` | `Path` | Não | `<input_file_without_ext>_selected.json` | Caminho do arquivo JSON de destino. Se omitido, grava no mesmo diretório com sufixo `_selected.json`. |
| `--indent` | `int` | Não | `2` | Número de espaços para indentação do JSON de saída. Use `0` para JSON compacto em linha única. |
| `-v`, `--verbose` | `flag` | Não | `False` | Exibe no `stderr` detalhes da pontuação e justificativa de escolha por artigo. |

---

## 3. Standard Streams (I/O)

- **`stdout`**:
  - Emite o sumário operacional em JSON ou texto resumido ao término da execução:
    ```json
    {
      "status": "success",
      "input_file": "out/river_plate_extracted.json",
      "output_file": "out/river_plate_extracted_selected.json",
      "total_articles": 20,
      "distribution": {
        "newspaper4k": 9,
        "readability": 9,
        "trafilatura": 2
      }
    }
    ```
- **`stderr`**:
  - Mensagens de log, progresso da barra/processamento de artigos e erros de validação ou exceções.

---

## 4. Exit Codes

| Código | Significado | Comportamento |
|:---:|---|---|
| `0` | **Sucesso** | Todos os artigos foram processados e o arquivo final foi gravado atomicamente com sucesso. |
| `1` | **Erro de I/O ou JSON Inválido** | Arquivo não encontrado, JSON malformado ou permissão negada. Nenhum arquivo de saída é gerado. |
| `2` | **Erro de Validação de Estrutura** | Raiz não é objeto ou chave `articles` não é uma lista. Nenhum arquivo de saída é gerado. |