Command Line Interface

Command-Line Interface

Relevant source files

The following files were used as context for generating this wiki page:

• clarity/cli.py
• tests/test_manifest_requeue.py

The command-line interface provides the primary operational dispatcher for the XIVUpscaler codebase. Implemented around a standard argument parser in clarity/cli.py, it coordinates database-backed manifest updates, GPU encoder checks, disk space safety verifications, and downstream texture processing pipelines.

graph TD
    subgraph "CLI Dispatcher Space (clarity/cli.py)"
    A["Main Parser Entrypoint\nclarity/cli.py"] --> B["cmd_plan\nclarity/cli.py:22"]
    A --> C["cmd_estimate\nclarity/cli.py:44"]
    A --> D["cmd_run\nChild Page 2.1"]
    A --> E["Maintenance Dispatchers\nChild Page 2.3"]
    end

    subgraph "Execution Subsystems"
    B --> F["mf.gen_chara / gen_icons\nclarity/manifest.py"]
    C --> G["man.summary()\nclarity/manifest.py"]
    D --> H["Engine & ThreadPoolExecutor\nclarity/processing/engine.py"]
    E --> I["cmd_requeue / cmd_audit\nclarity/cli.py"]
    end

    style A fill:#fff,stroke:#000,stroke-width:2px
    style B fill:#fff,stroke:#000,stroke-width:1px
    style C fill:#fff,stroke:#000,stroke-width:1px
    style D fill:#fff,stroke:#000,stroke-width:1px
    style E fill:#fff,stroke:#000,stroke-width:1px

Loading

Sources: clarity/cli.py:1-42, clarity/manifest.py:1-50

---

2.1. The Run Loop and Batch Encoding

The core execution loop is governed by cmd_run (detailed in child page 2.1). It handles model slot selection, concurrent texture encoding via ThreadPoolExecutor, batch metrics (--encode-batch, --encode-workers, --encode-mb), memory budgets, resumability flags, and failure logging.

Before execution begins, prerequisite validations such as check_encoder (clarity/cli.py:95-122) and check_disk (clarity/cli.py:154-172) evaluate available hardware capabilities and target volume capacity to prevent runtime failures mid-pipeline.

For full details on parallel execution, queue processing, and error management, see The Run Loop and Batch Encoding.

Sources: clarity/cli.py:95-172

---

2.2. Planning, Estimation and Probing

Planning and asset ingestion are handled via cmd_plan and cmd_estimate (clarity/cli.py:22-93). cmd_plan initializes database rows through character enumeration (mf.gen_chara), icon discovery (mf.gen_icons), or ResLogger pathlist ingestion (mf.from_pathlist), followed by synchronizing skipped processing paths (clarity/cli.py:36-40).

graph LR
    subgraph "Planning Pipeline"
    P1["cmd_plan\nclarity/cli.py:22"] --> P2["mf.gen_chara / mf.gen_icons\nclarity/manifest.py"]
    P1 --> P3["mf.from_pathlist\nclarity/manifest.py"]
    P2 --> P4["mf.sync_skipped\nclarity/cli.py:36"]
    P3 --> P4
    P4 --> P5["cmd_estimate\nclarity/cli.py:44"]
    end

    style P1 fill:#fff,stroke:#000,stroke-width:2px
    style P5 fill:#fff,stroke:#000,stroke-width:1px

Loading

cmd_estimate queries the manifest summary table and computes targeted storage projections across native, 2x, and 4x generation tiers using per-role scaling factors (clarity/cli.py:44-93).

For full details on pathlist parsing, diagnostics, and probe subcommands, see Planning, Estimation and Probing.

Sources: clarity/cli.py:22-93, clarity/manifest.py:1-100

---

2.3. Maintenance Commands: requeue, reclassify, fingerprint, audit, modup

Maintenance operations provide lifecycle controls for administrative patches and iterative asset correction. These utilities handle patch-delta tracking, reclassification filters, fingerprint differentials, and third-party mod integration.

Crucially, commands like cmd_requeue preserve patch-delta status markers (such as changed at <version>) while clearing transient processing errors, allowing selective delta runs via run --since (tests/test_manifest_requeue.py:1-56).

graph TD
    subgraph "Maintenance Actions"
    M1["cmd_requeue\ntests/test_manifest_requeue.py:50"] --> M2["Preserve changed at Markers\nclarity/cli.py"]
    M1 --> M3["Clear Transient Failures\nclarity/cli.py"]
    M4["cmd_audit\nclarity/cli.py"] --> M5["Validate Policy Constants\nroles.MAX_EDGE_OUT\ntests/test_manifest_requeue.py:90"]
    end

    style M1 fill:#fff,stroke:#000,stroke-width:2px
    style M4 fill:#fff,stroke:#000,stroke-width:2px

Loading

For full details on requeue semantics, manifest audits, reclassification, and mod upscaling (modtex.py, uldparts.py), see Maintenance Commands: requeue, reclassify, fingerprint, audit, modup.

Sources: clarity/cli.py:1-172, tests/test_manifest_requeue.py:1-96