CLI

Boundary

NexusScholar.Cli parses arguments and renders structured application results. Domain rules live in Core packages; local-folder orchestration lives in ResearchWorkspace. The CLI does not become scientific authority merely because it is the process entry point.

CliApplication.Run is the authoritative command dispatcher. Program.cs delegates directly to it, which keeps handlers testable with explicit output, error, working directory, and clock inputs.

Current command families

• Environment and deterministic smoke: doctor, sample, demo. Doctor reports runtime and product laws; sample exercises Protocol, Workflow, Provenance, and Bundle verification; demo runs in-memory Search import and Deduplication with no network or persistence.
• Workspace lifecycle: init --title "<title>" [--workspace-id <id>], status, verify.
• Local evidence intake: import search <path> --source <source> --format <format> [--query-id <id>] [--query <text>].
• Analysis and inspection: analyze, review, clusters, clusters exact, clusters review, clusters show <cluster-or-candidate-id>.
• Human FE-02 decision: dedup decide --target <id> --action <action> --reason <code> --actor <id> --role <role> [--rationale <text>] [--supersedes <decision-id>] [--confirm].
• Screening inspection: screening status verifies the current persisted conduct manifest and artifact inventory. Its output explicitly says that full authority is not rehydrated.
• Persisted artifact verification: report verify <export-id>, bundle verify <export-id>, export verify <export-id>, and export status.

Workspace path

nexus init --title "Evidence review"
nexus import search ./exports/scopus.csv --source scopus --format csv
nexus verify
nexus analyze
nexus review
nexus clusters review
nexus dedup decide --target dedup-target-... \
  --action keep-separate --reason distinct-studies \
  --actor researcher-1 --role reviewer
# preview only

# repeat exact command with --confirm to commit

dedup decide previews by default. --confirm commits the exact reconstructed preview. Authorization comes from the verified local policy assignment, not the supplied actor/role strings. Corrections require --supersedes to name the exact active decision.

Verification semantics

report verify checks persisted canonical report and slice bytes plus ledger bindings, and explicitly reports that source-authority replay was not performed. bundle verify rehydrates Bundle v2 and compares the exact on-disk inventory. export verify replays the export ledger and selects one immutable entry. export status prints the verified ledger count, head, entries, and unreferenced exports.

These commands accept an export id only. They do not accept caller-supplied digests, counts, actor text, Protocol ids, or generation ids as substitute authority.

Exit codes and failure states

0  success
1  usage or validation failure
2  missing project or input
3  digest mismatch
4  unsupported schema or import format
5  unexpected runtime failure

Command output avoids machine-local absolute paths when a project-relative description is available. Stale and recovery conditions originate in ResearchWorkspace; the adapter maps them to explicit messages and stable exit codes rather than silently retrying scientific mutations.

Dependencies, tests, and extension rules

The CLI references the modules needed for the smoke commands plus ResearchWorkspace, AppServices, Reporting, UiContracts, AI, and Extensibility contracts. A project reference does not imply a runtime: the CLI does not execute plugins or models.

CLI tests cover process behavior, workspace lifecycle, import, verification, analysis, review/clusters, deduplication decisions, local demo, and persisted artifact verification. The local workflow is documented in RESEARCH-WORKSPACE-CLI-v0.

New commands should remain thin adapters over typed operations. Do not parse another adapter’s console output or reimplement transaction/authority logic in command handlers.

Explicit nonclaims

No live provider, scraping, PDF/OCR, AI/model call, plugin execution, database, API, cloud, multi-user, authentication, full source-authority replay for report verify, broad PHP compatibility, or production CLI stability is claimed.