CLI Reference

This page provides a complete reference for the OpenConvert command-line interface.

Synopsis

openconvert [GLOBAL_OPTIONS] -i INPUT -o OUTPUT [OPTIONS]
openconvert [GLOBAL_OPTIONS] --list-formats
openconvert --help
openconvert --version

Global Options

These options apply to all OpenConvert commands:

--help

Show help message and exit.

--version

Show version information and exit.

-v, --verbose

Enable verbose output. Shows detailed progress information during conversion.

-q, --quiet

Enable quiet mode. Suppress all output except errors.

--host HOST

Specify the network host to connect to.

Default:

network.openconvert.ai

Example:

--host convert.example.com

--port PORT

Specify the network port to connect to.

Default:

8765

Example:

--port 9000

Core Commands

File Conversion

Convert files between different formats:

openconvert -i INPUT -o OUTPUT [OPTIONS]

Required Arguments:

-i INPUT, --input INPUT

Input file or directory path. Can be:

  • Single file: document.txt

  • Directory: documents/

  • Glob pattern: *.txt (shell expansion)

-o OUTPUT, --output OUTPUT

Output file or directory path. The output format is usually detected from the file extension.

Optional Arguments:

--from MIME_TYPE

Source MIME type. Override automatic format detection.

Example:

--from text/csv

--to MIME_TYPE

Target MIME type. Override automatic format detection from output extension.

Example:

--to application/pdf

--prompt TEXT

Natural language instructions for enhanced conversion. Not all agents support prompts.

Example:

--prompt "Create professional layout with charts"

Format Discovery

List available format conversions:

openconvert --list-formats

This command connects to the network and displays all available conversion capabilities from connected agents.

Examples

Basic Conversions

# Simple text to PDF conversion
openconvert -i document.txt -o document.pdf

# Image format conversion
openconvert -i photo.jpg -o photo.png

# Convert with explicit formats
openconvert -i data.csv -o chart.png \\
  --from text/csv --to image/png

Batch Processing

# Convert all files in directory
openconvert -i documents/ -o converted/

# Convert specific format across directory
openconvert -i photos/ -o thumbnails/ \\
  --from image/jpeg --to image/webp

# Convert multiple files with shell expansion
openconvert -i *.txt -o pdfs/ --to application/pdf

Enhanced Conversions

# Document with custom formatting
openconvert -i report.txt -o report.pdf \\
  --prompt "Professional layout with headers and TOC"

# Image processing with instructions
openconvert -i large.jpg -o small.jpg \\
  --prompt "Resize to 800px width, optimize for web"

# Data visualization
openconvert -i sales.csv -o charts.pdf \\
  --prompt "Create bar charts showing monthly trends"

Network Operations

# Connect to remote network
openconvert --host remote.example.com --port 9000 \\
  -i file.txt -o file.pdf

# List formats from specific network
openconvert --host convert.company.com --list-formats

# Verbose mode for debugging
openconvert -v -i document.txt -o document.pdf

MIME Types Reference

Common Document Types

MIME Type

Extension

Description

text/plain

.txt

Plain text files

text/csv

.csv

Comma-separated values

text/markdown

.md

Markdown documents

application/pdf

.pdf

PDF documents

application/vnd.openxmlformats-officedocument.wordprocessingml.document

.docx

Word documents

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

.xlsx

Excel spreadsheets

Common Image Types

MIME Type

Extension

Description

image/jpeg

.jpg, .jpeg

JPEG images

image/png

.png

PNG images

image/gif

.gif

GIF images

image/webp

.webp

WebP images

image/svg+xml

.svg

SVG graphics

image/tiff

.tiff, .tif

TIFF images

Audio and Video Types

MIME Type

Extension

Description

audio/mpeg

.mp3

MP3 audio

audio/wav

.wav

WAV audio

audio/ogg

.ogg

OGG audio

video/mp4

.mp4

MP4 video

video/webm

.webm

WebM video

video/quicktime

.mov

QuickTime video

Exit Codes

OpenConvert uses standard exit codes:

Code

Description

0

Success

1

General error (conversion failed, invalid arguments, etc.)

2

Network error (cannot connect to agents)

3

File error (input not found, output not writable, etc.)

4

Format error (unsupported format, no suitable agent, etc.)

Environment Variables

OpenConvert recognizes these environment variables:

OPENCONVERT_HOST

Default network host. Overrides the built-in default of localhost.

OPENCONVERT_PORT

Default network port. Overrides the built-in default of 8765.

OPENCONVERT_VERBOSE

Enable verbose mode if set to 1, true, or yes.

OPENCONVERT_QUIET

Enable quiet mode if set to 1, true, or yes.

Example:

export OPENCONVERT_HOST=convert.company.com
export OPENCONVERT_PORT=9000
export OPENCONVERT_VERBOSE=1

# Now all commands use these defaults
openconvert -i file.txt -o file.pdf

Configuration Files

Note

Configuration file support is planned for future releases.

Future versions will support configuration files for default settings:

# ~/.openconvert.yaml (planned)
network:
  host: convert.company.com
  port: 9000

defaults:
  verbose: true
  prompt_template: "Professional formatting"

agents:
  preferred:
    - doc-agent-premium
    - image-agent-fast

Shell Completion

Note

Shell completion support is planned for future releases.

Future versions will include shell completion for:

  • Command options

  • MIME types

  • Available agents

  • File paths

Usage Patterns

Workflow Examples

Document Processing Workflow:

# 1. Check available document conversions
openconvert --list-formats | grep document

# 2. Convert with basic formatting
openconvert -i draft.txt -o draft.pdf

# 3. Enhanced conversion with custom prompt
openconvert -i final.txt -o final.pdf \\
  --prompt "Executive summary format with logo"

Batch Image Processing:

# 1. Test with single image
openconvert -i sample.jpg -o sample.webp \\
  --prompt "Compress for web"

# 2. Process entire directory
openconvert -i photos/ -o web-ready/ \\
  --from image/jpeg --to image/webp \\
  --prompt "Compress for web, maintain quality"

Data Visualization Pipeline:

# 1. Create basic chart
openconvert -i data.csv -o preview.png \\
  --prompt "Simple bar chart"

# 2. Generate final report
openconvert -i data.csv -o report.pdf \\
  --prompt "Executive dashboard with multiple charts and analysis"

Command Chaining

Combine OpenConvert with other tools:

# Find and convert all text files
find . -name "*.txt" -exec openconvert -i {} -o {}.pdf \\;

# Convert and compress
openconvert -i large.png -o temp.webp && \\
openconvert -i temp.webp -o small.webp --prompt "Further compress"

# Parallel processing with xargs
ls *.txt | xargs -I {} -P 4 openconvert -i {} -o {}.pdf

Performance Tips

  1. Use explicit formats to avoid detection overhead

  2. Test prompts on small files before batch processing

  3. Connect to local networks for better performance

  4. Use appropriate agents - check --list-formats for capabilities

  5. Monitor verbose output to identify bottlenecks

Troubleshooting

For detailed troubleshooting information, see Troubleshooting.

Common quick fixes:

# Connection issues
openconvert --host localhost --port 8765 --list-formats

# Format issues
openconvert --list-formats | grep "text/plain"

# Verbose debugging
openconvert -v -i problem.txt -o output.pdf

See Also