Skip to content

CLI User Guide

Overview

orc-cli is the command-line interface for Decode Orc, a cross-platform orchestration and processing framework for LaserDisc and tape decoding workflows. It provides a text-based interface for batch processing video projects defined in .orcprj files.

The CLI uses the same core processing library as the GUI (orc-gui), ensuring that project files created in the graphical interface can be executed unchanged via the command line, and vice versa.

Key Features

  • Batch Processing: Process complete DAG pipelines without user interaction
  • Automation: Integrate into scripts and automated workflows
  • Reproducibility: Execute the same project file consistently across runs
  • Progress Tracking: Real-time progress updates during processing
  • Flexible Logging: Configurable logging levels and output destinations
  • Crash Reporting: Automatic diagnostic bundle creation for troubleshooting

Basic Usage

Command Syntax

orc-cli <project-file> [options]

Required Arguments

  • <project-file>: Path to an Orc project file (.orcprj)

Options

Option Description Default
--process Process the complete DAG pipeline (trigger all sink nodes) Required
--log-level LEVEL Set logging verbosity level info
--log-file FILE Write logs to specified file None (console only)
--help, -h Display help message and exit -

Log Levels

Available log levels (from most to least verbose):

  • trace: Extremely detailed debugging information
  • debug: Detailed debugging information
  • info: General informational messages
  • warn: Warning messages
  • error: Error messages
  • critical: Critical errors only
  • off: Disable logging

Examples

Basic Processing

Process a project file with default settings:

orc-cli my-project.orcprj --process

Detailed Logging

Enable debug logging for troubleshooting:

orc-cli my-project.orcprj --process --log-level debug

Log to File

Save all log output to a file:

orc-cli my-project.orcprj --process --log-file processing.log

Combined Options

Process with debug logging saved to file:

orc-cli my-project.orcprj --process --log-level debug --log-file debug.log

Processing Workflow

When you run orc-cli --process, the following occurs:

  1. Project Loading: The .orcprj file is loaded and validated
  2. DAG Construction: The processing pipeline is built from the project definition
  3. Validation: Input files and parameters are verified
  4. Sink Triggering: All sink nodes in the DAG are triggered sequentially
  5. Progress Reporting: Real-time progress updates are displayed (every 5%)
  6. Completion: Exit code indicates success (0) or failure (non-zero)

Progress Output

During processing, you'll see progress updates like:

[2026-02-08 10:15:23.456] [cli] [info] Loading project: my-project.orcprj
[2026-02-08 10:15:23.789] [cli] [info] Project loaded: My Video Project
[2026-02-08 10:15:24.012] [cli] [info] [Progress: 0%] Starting decoding...
[2026-02-08 10:15:45.234] [cli] [info] [Progress: 5%] Processing frames...
[2026-02-08 10:16:12.567] [cli] [info] [Progress: 10%] Processing frames...
...
[2026-02-08 10:25:34.890] [cli] [info] [Progress: 100%] Decode complete

Exit Codes

  • 0: Success - all operations completed successfully
  • 1: Error - processing failed or invalid arguments

Always check the exit code in scripts:

if orc-cli project.orcprj --process; then
    echo "Processing successful!"
else
    echo "Processing failed!" >&2
    exit 1
fi

Project Files

Project File Format

Project files (.orcprj) are YAML-based files that define:

  • Source configurations (input TBC files)
  • DAG structure (processing nodes and connections)
  • Node parameters (decoder settings, output formats, etc.)
  • Project metadata (name, description, video format)
  • Optional required_plugins metadata for third-party plugin-backed stages

When a project contains stages supplied by third-party plugins, Decode-Orc now saves a root-level required_plugins block in the .orcprj file. Each entry records the plugin identity, repository or release URL metadata, ABI expectation, and the stage names from that plugin that are still used by the project.

This block is refreshed every time the project is saved:

  • Plugin entries are kept only if at least one of their stage names is still present in the current DAG
  • Plugin metadata is refreshed from the current local plugin registry when available
  • Stale entries are removed automatically if the corresponding plugin-backed stages were deleted while editing

If a project is opened on a machine where one of those stages is unavailable, Decode-Orc uses the saved required_plugins metadata to give a more specific missing-stage error that can point the user at the expected plugin and its repository URL.

Creating Projects

Project files are typically created using orc-gui, but they can also be:

  • Hand-edited (with care - see technical documentation)
  • Generated programmatically
  • Version controlled (recommended for reproducibility)

Project Compatibility

Projects created in the GUI can be executed in the CLI without modification. This ensures:

  • Consistent results across interfaces
  • Batch processing of GUI-created projects
  • Easy integration into automated workflows

Common Use Cases

Batch Processing Multiple Files

Process multiple projects in a loop:

for project in *.orcprj; do
    echo "Processing $project..."
    orc-cli "$project" --process --log-level info
done

Automated Workflow

Integrate into a processing pipeline:

#!/bin/bash
set -e

# Process video
orc-cli capture1.orcprj --process --log-file capture1.log

# Check for errors
if [ $? -ne 0 ]; then
    echo "Processing failed, check capture1.log"
    exit 1
fi

# Continue with next step...

Monitoring Progress

Capture and monitor progress in real-time:

orc-cli project.orcprj --process 2>&1 | tee -a processing.log

Error Handling

Common Errors

Project file not found: 

Error: No project file specified
→ Ensure the .orcprj file path is correct

Missing command: 

Error: No command specified. You must use --process
→ Add the --process flag

Processing failure: 

Failed to load project: <reason>
→ Check project file syntax and input file paths

Crash Diagnostics

If orc-cli crashes unexpectedly, it automatically creates a diagnostic bundle containing:

  • System information (OS, CPU, memory)
  • Stack backtrace showing crash location
  • Application logs
  • Core dump file (when available)

The crash bundle is saved as a ZIP file in the current working directory:

crash-bundle-orc-cli-YYYY-MM-DD-HHMMSS.zip

When reporting issues, attach this bundle to your bug report on GitHub Issues.