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)

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.