---
description: |
  [TOPIC] Drift_Report
  [DETAILS] SciTeX Ecosystem CLI Drift Report — see file body for details.
tags: [scitex-general-interface-cli-DRIFT-REPORT]
---

# SciTeX Ecosystem CLI Drift Report

Generated by `scitex-dev ecosystem audit-cli` against installed `scitex-*` console scripts (date: 2026-04-30). Static checks only — `--behavioral` not run. Warn-only; no fixes applied.

The auditor handles three CLI shapes: native Click trees, wrapper functions that re-export a Click root, and **argparse parsers captured via a parse-call interceptor**. Each package is invoked under a separate Python subprocess with stdin redirected to `/dev/null` and stdio redirected to devnull during entry-point load — so MCP servers that close stdio or steal stdin no longer poison the audit run.

## Per-package totals (28 audited / 38 total)

| Package                | Warnings | Top rule classes                    |
|------------------------|---------:|-------------------------------------|
| crossref-local         |       19 | §4 (13), §1 (4), §2 (2)             |
| figrecipe              |       66 | §4 (30), §2 (20), §1 (14)           |
| openalex-local         |       37 | §4 (22), §2 (10), §1 (4)            |
| scitex                 |       12 | §1a (2), §6b, §1d                   |
| scitex-agent-container |       67 | §4 (31), §1 (17), §2 (15)           |
| scitex-app             |       22 | §2 (12), §4 (9)                     |
| scitex-audio           |       15 | §4 (7), §2 (7)                      |
| scitex-capture         |        3 | §1a (2), §6b                        |
| scitex-cloud           |      138 | §2 (80), §4 (57)                    |
| scitex-container       |       61 | §2 (32), §4 (26), §1a (2)           |
| scitex-dataset         |       30 | §4 (21), §2 (8)                     |
| scitex-db              |       10 | §4, §2, §1a                         |
| scitex-dev             |       41 | §4 (24), §2 (14)                    |
| scitex-hpc             |       14 | §2, §4, §1a                         |
| scitex-io              |       25 | §4 (14), §2 (7), §1a (2)            |
| scitex-linter          |       34 | §4, §2, §1a                         |
| scitex-notebook        |       13 | §2 (6), §4 (4), §1a (2)             |
| scitex-notification    |       16 | §2 (9), §4 (6)                      |
| scitex-orochi          |      102 | §2 (33), §4 (31), §1 (16), §6a (14) |
| scitex-pkg             |        6 | §2 (2), §1a (2)                     |
| scitex-plt             |       67 | §4 (30), §2 (20), §1 (14)           |
| scitex-scholar         |       25 | §4, §2, §1a                         |
| scitex-security        |        9 | §2, §4, §1a                         |
| scitex-ssh             |       27 | §4 (11), §2 (10), §1 (3), §1a (2)   |
| scitex-stats           |       18 | §4, §2, §1a                         |
| scitex-template        |       16 | §4, §2, §1a                         |
| scitex-ui              |       10 | §4 (5), §2 (3)                      |
| scitex-writer          |       89 | §4, §2, §1a                         |
| socialia               |       77 | §4, §2                              |

### Skipped (10) — not user-facing CLIs or load failures

- **MCP / agent server entry points** (not user-facing — protocol servers): `scitex-cloud-mcp`, `scitex-container-mcp`, `scitex-diagram`, `scitex-mcp-server`, `scitex-orochi-mcp`, `scitex-orochi-server`, `scitex-template-mcp`.
- **Module-not-found at load time**: `scitex-canvas`, `scitex-tunnel`. Likely stale / partial install.

## Aggregate by rule (across all 28 audited packages)

| Rule | Hits | Meaning                                                                  |
|------|-----:|--------------------------------------------------------------------------|
| §4   |  486 | Missing concrete example in command help/epilog.                         |
| §2   |  368 | Missing universal flag (`--json`, `--dry-run`, `-y`, `-V`, `--help-recursive`). |
| §1   |  122 | Noun-verb structure violation (bare verb, trailing noun, group-as-verb). |
| §1a  |   26 | Missing introspection commands (`list-python-apis`, `mcp list-tools`) or their `--json`. |
| §1d  |   25 | Vocabulary token not in catalog/dict/Moby.                               |
| §6b  |   24 | Top-level `--help` doesn't document config-path fallback.                |
| §6a  |   14 | Bare package-name env-var prefix (concentrated in scitex-orochi).        |
| §1b  |    4 | Banned bare leaf (`version` / `completion`).                             |

**Total warnings: 1067** across the audited subset.

## Highest-leverage fixes

1. **§4 (486 hits)** — One-line `Example:` epilog on every leaf command would clear ~⅖ of all warnings.
2. **§2 (368 hits)** — Most are read commands missing `--json` and mutating commands missing `--dry-run` / `--yes`. A shared decorator helper would absorb most of these.
3. **§1a (26 hits)** — Bring the introspection ladder (`list-python-apis`, `mcp list-tools`) to the holdouts: `scitex-container`, `scitex-io`, `scitex-notebook`, `scitex-pkg`, `scitex-ssh`, `scitex-ui`, plus all the argparse packages now caught by the new adapter.
4. **§6b (24 hits)** — Add a one-paragraph "Config" section to each top-level `--help` mentioning `config.yaml`, `$SCITEX_<PKG>_CONFIG`, and the `~/.scitex/` fallback.
5. **§1b (4 hits)** — Easy: rename surviving `version` / `completion` subcommands to flags / compound-leaf verbs.

## Reproduction

Per-package warning files live in `/tmp/cli-drift/<package>.txt`. Regenerate with:

```bash
: > /tmp/cli-drift/summary.txt
while read pkg; do
  out=$(timeout 25 python -c "from scitex_dev._cli_audit import audit_cli; raise SystemExit(audit_cli('$pkg'))" </dev/null 2>&1)
  echo "$pkg $out" >> /tmp/cli-drift/summary.txt
  echo "$out" > "/tmp/cli-drift/$pkg.txt"
done < <(scitex-dev ecosystem list | awk '{print $1}')
```

## Auditor coverage gaps

- Behavioral checks (`--behavioral`) were not run ecosystem-wide here — they invoke each CLI as a subprocess (slow, side-effect risk).
- §1c pass-through entries (verbatim-forwarding entry points like `<cli> git ...`) are still not auto-detected.
- §5 hard-error redirect on renamed commands is not enforced (auditor skips `hidden=True` commands).
- §7 CLI ↔ MCP parity (compare `list-python-apis` and `mcp list-tools` output) is still TODO.
