OWA CLI (`owl`) - Command Line Tools¶

The owl command provides comprehensive tools for working with OWA data, environments, and message types. It's your primary interface for managing MCAP files, environment plugins, message schemas, and video processing.

Installation¶

The CLI is included with the owa-cli package:

pip install owa-cli

After installation, the owl command becomes available in your terminal.

Quick Start¶

# Get help for any command
owl --help
owl mcap --help

# Common workflows
owl mcap info session.mcap              # Inspect MCAP files
owl env list                            # List environment plugins  
owl messages show desktop/MouseEvent    # View message schemas
owl video probe recording.mkv           # Analyze video files

Command Groups¶

The owl CLI is organized into specialized command groups:

📁 MCAP Commands (`owl mcap`)¶

Tools for working with MCAP files - the core data format for multimodal desktop recordings.

Key commands: info, cat, convert, migrate, sanitize

owl mcap info session.mcap              # File information
owl mcap cat session.mcap --n 10        # View messages  
owl mcap convert session.mcap           # Convert to subtitles

🔌 Environment Commands (`owl env`)¶

Manage environment plugins that capture desktop data and provide system integration.

Key commands: list, search, validate, stats, docs

owl env list                            # List all plugins
owl env list desktop                    # Plugin details
owl env search keyboard                 # Find components
owl env stats --namespaces              # Show namespaces

📋 Message Commands (`owl messages`)¶

Inspect and validate message type schemas used in MCAP files.

Key commands: list, show, validate

owl messages list                       # All message types
owl messages show desktop/KeyboardEvent # Schema details
owl messages validate                   # Validate definitions

🎥 Video Commands (`owl video`)¶

Process and analyze video files from OWA recordings.

Key commands: probe, vfr-to-cfr

owl video probe session.mkv            # Analyze video
owl video vfr-to-cfr session.mkv       # Convert frame rate

Complete Command Reference¶

owl¶

owl - Open World agents cLi - Tools for managing OWA data and environments

Usage:

owl [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--silent`, `-s`	boolean	Suppress non-essential output	`False`
`--no-update-check`	boolean	Skip version update check	`False`
`--install-completion`	boolean	Install completion for the current shell.	None
`--show-completion`	boolean	Show completion for the current shell, to copy it or customize the installation.	None
`--help`	boolean	Show this message and exit.	`False`

owl env¶

Environment plugin management commands

Usage:

owl env [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

owl env docs¶

Validate plugin documentation quality and show statistics.

Always validates documentation and returns meaningful exit codes: - 0: All validations passed - 1: Documentation issues found (warnings or failures) - 2: Command error (invalid arguments, plugin not found, etc.)

Usage:

owl env docs [OPTIONS] [PLUGIN_NAMESPACE]

Options:

Name	Type	Description	Default
`--strict`	boolean	Enable strict mode (100% coverage + 100% quality)	`False`
`--min-coverage-pass`	float	Minimum coverage for PASS status	`0.8`
`--min-coverage-fail`	float	Minimum coverage to avoid FAIL status	`0.6`
`--min-quality-pass`	float	Minimum good quality ratio for PASS status	`0.6`
`--min-quality-fail`	float	Minimum good quality ratio to avoid FAIL status	`0.0`
`--output-format`	text	Output format: table or json	`table`
`--by-type`	boolean	Group statistics by component type (table format only)	`False`
`--help`	boolean	Show this message and exit.	`False`

owl env list¶

List environment plugins and components.

Usage:

owl env list [OPTIONS] [NAMESPACES]...

Options:

Name	Type	Description	Default
`--components`, `-c`	boolean	Show individual components	`False`
`--details`, `-d`	boolean	Show import paths and load status	`False`
`--table`	boolean	Display in table format	`False`
`--type`, `-t`	text	Filter by component type (callables/listeners/runnables)	None
`--search`, `-s`	text	Search components by name pattern	None
`--inspect`	text	Inspect specific component (show docstring/signature)	None
`--help`	boolean	Show this message and exit.	`False`

owl env search¶

Search for components across all plugins using pattern matching.

Usage:

owl env search [OPTIONS] PATTERN

Options:

Name	Type	Description	Default
`--type`, `-t`	text	Filter by component type	None
`--namespace`, `-n`	text	Filter by namespace	None
`--case-sensitive`, `-c`	boolean	Case sensitive search	`False`
`--details`, `-d`	boolean	Show detailed component information	`False`
`--table`	boolean	Display results in table format	`False`
`--limit`, `-l`	integer	Limit number of results	`50`
`--help`	boolean	Show this message and exit.	`False`

owl env stats¶

Show comprehensive statistics about the plugin ecosystem.

Usage:

owl env stats [OPTIONS]

Options:

Name	Type	Description	Default
`--detailed`, `-d`	boolean	Show detailed statistics	`False`
`--by-namespace`, `-n`	boolean	Group statistics by namespace	`False`
`--by-type`, `-t`	boolean	Group statistics by component type	`False`
`--loaded-only`, `-l`	boolean	Show statistics for loaded components only	`False`
`--namespaces`	boolean	Show available namespaces	`False`
`--help`	boolean	Show this message and exit.	`False`

owl env validate¶

Validate a plugin specification from YAML file or entry point.

This command can validate plugin specifications in two ways:

From YAML files: owl env validate ./plugin.yaml
From entry points: owl env validate owa.env.plugins.desktop:plugin_spec

The command automatically detects the input type and validates accordingly.

Usage:

owl env validate [OPTIONS] SPEC_INPUT

Options:

Name	Type	Description	Default
`--check-imports` / `--no-check-imports`	boolean	Validate that component import paths are accessible	`True`
`--verbose`, `-v`	boolean	Show detailed validation information	`False`
`--help`	boolean	Show this message and exit.	`False`

owl mcap¶

MCAP file management commands

Usage:

owl mcap [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

owl mcap cat¶

Print messages from an .mcap file in a readable format.

Usage:

owl mcap cat [OPTIONS] MCAP_PATH

Options:

Name	Type	Description	Default
`--pretty` / `--no-pretty`	boolean	Pretty print JSON output	`True`
`--topics`	text	Topics to include (space-separated or multiple --topics flags)	None
`--exclude`	text	Topics to exclude (space-separated or multiple --exclude flags)	None
`--start-time`	integer	Start time in seconds	None
`--end-time`	integer	End time in seconds	None
`--n`	integer	Number of messages to print	None
`--help`	boolean	Show this message and exit.	`False`

owl mcap convert¶

Convert an .mcap file into an .srt subtitle file. After the conversion, you may play .mkv file and verify the sanity of data.

Usage:

owl mcap convert [OPTIONS] MCAP_PATH [OUTPUT_SRT]

Options:

Name	Type	Description	Default
`--topics`	text	Comma-separated list of topics to include in the subtitle file	`['mouse/raw', 'mouse', 'keyboard']`
`--help`	boolean	Show this message and exit.	`False`

owl mcap convert-overlay¶

Convert an .mcap file into a video with overlays showing mouse clicks and keyboard presses.

Usage:

owl mcap convert-overlay [OPTIONS] MCAP_PATH [OUTPUT_VIDEO]

Options:

Name	Type	Description	Default
`--topics`	text	Comma-separated list of topics to include in the overlay	`['mouse/raw', 'keyboard']`
`--fps`	float	Output video frame rate (default: use original MCAP frame rate)	None
`--max-duration-seconds`	float	Maximum duration in seconds to generate (default: entire video)	None
`--original-width`	integer	Original recording width resolution for mouse movement scaling	`2560`
`--original-height`	integer	Original recording height resolution for mouse movement scaling	`1440`
`--help`	boolean	Show this message and exit.	`False`

owl mcap info¶

Display information about the .mcap file(s). Shows detailed info for single file, summary for multiple files.

Usage:

owl mcap info [OPTIONS] MCAP_PATHS...

Options:

Name	Type	Description	Default
`--force-upgrade`	boolean	Force upgrade mcap CLI to latest version	`False`
`--help`	boolean	Show this message and exit.	`False`

owl mcap migrate¶

MCAP migration commands with rollback and cleanup support.

Usage:

owl mcap migrate [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

owl mcap migrate cleanup¶

Clean up MCAP backup files.

This command finds backup files (.mcap.backup) using the specified patterns and removes them after confirmation. Use --dry-run to preview what would be deleted.

Examples: owl mcap migrate cleanup # Clean all backup files in current directory tree owl mcap migrate cleanup "*.mcap.backup" # Clean backup files in current directory only owl mcap migrate cleanup /path/to/backups # Clean backup files in specific directory owl mcap migrate cleanup file.mcap # Clean backup for specific MCAP file

Usage:

owl mcap migrate cleanup [OPTIONS] [PATTERNS]...

Options:

Name	Type	Description	Default
`--dry-run`	boolean	Show what would be deleted without actually deleting	`False`
`--yes`, `-y`	boolean	Skip confirmation prompt	`False`
`--verbose`, `-v`	boolean	Show detailed cleanup information	`False`
`--help`	boolean	Show this message and exit.	`False`

owl mcap migrate rollback¶

Rollback MCAP files from their backup files.

This command finds backup files (.mcap.backup) corresponding to the specified MCAP files and restores the original files from the backups. The backup files are removed after successful rollback.

Usage:

owl mcap migrate rollback [OPTIONS] FILES...

Options:

Name	Type	Description	Default
`--yes`, `-y`	boolean	Skip confirmation prompt	`False`
`--verbose`, `-v`	boolean	Show detailed rollback information	`False`
`--help`	boolean	Show this message and exit.	`False`

owl mcap migrate run¶

Migrate MCAP files to the highest reachable version with automatic version detection.

Usage:

owl mcap migrate run [OPTIONS] FILES...

Options:

Name	Type	Description	Default
`--target`, `-t`	text	Target version (default: highest reachable)	None
`--dry-run`	boolean	Show what would be migrated without making changes	`False`
`--verbose`, `-v`	boolean	Show detailed migration information	`False`
`--keep-backups` / `--no-backups`	boolean	Keep backup files after migration	`True`
`--yes`, `-y`	boolean	Skip confirmation prompt	`False`
`--help`	boolean	Show this message and exit.	`False`

owl mcap rename-uri¶

Rename URIs in mediaref fields of screen topic events in MCAP files.

This command processes MCAP files to set all URIs in the mediaref fields of screen topic events to the specified new URI. This is useful for updating file paths or URLs when media files have been moved or renamed.

Examples: owl mcap rename-uri recording.mcap --uri "new_video.mkv" owl mcap rename-uri *.mcap --uri "/new/path/video.mp4" owl mcap rename-uri data.mcap --uri "http://new.com/video" --dry-run

Usage:

owl mcap rename-uri [OPTIONS] FILES...

Options:

Name	Type	Description	Default
`--uri`	text	URI to use for all screen topic events	_required
`--dry-run`	boolean	Show what would be changed without making modifications	`False`
`--verbose`, `-v`	boolean	Show detailed processing information	`False`
`--yes`, `-y`	boolean	Skip confirmation prompt	`False`
`--keep-backups` / `--no-backups`	boolean	Keep backup files after processing	`True`
`--help`	boolean	Show this message and exit.	`False`

owl mcap sanitize¶

Sanitize MCAP files by keeping only events when a specific window is active.

This command filters MCAP files to retain only the events that occurred when the specified window was active, effectively removing data from other applications for privacy or focus purposes.

Safety feature: By default, the operation will be blocked if more than 20% of messages would be removed, preventing accidental over-sanitization. Use --max-removal-ratio to adjust this threshold.

Examples: owl mcap sanitize recording.mcap --keep-window "Notepad" owl mcap sanitize *.mcap --keep-window "Work App" --exact owl mcap sanitize data.mcap --keep-window "Browser" --dry-run owl mcap sanitize data.mcap --keep-window "App" --max-removal-ratio 0.95 owl mcap sanitize recording.mcap --auto-detect-window

Usage:

owl mcap sanitize [OPTIONS] FILES...

Options:

Name	Type	Description	Default
`--keep-window`	text	Window name to keep events for	None
`--auto-detect-window`	boolean	Auto-detect the most frequent window to keep	`False`
`--exact` / `--substring`	boolean	Use exact window name matching (default: substring)	`False`
`--dry-run`	boolean	Show what would be changed without making modifications	`False`
`--verbose`, `-v`	boolean	Show detailed sanitization information	`False`
`--yes`, `-y`	boolean	Skip confirmation prompt	`False`
`--keep-backups` / `--no-backups`	boolean	Keep backup files after sanitization	`True`
`--max-removal-ratio`	float range (between `0.0` and `1.0`)	Maximum ratio of messages that can be removed (0.0-1.0). Safety feature to prevent accidental over-sanitization.	`0.2`
`--help`	boolean	Show this message and exit.	`False`

owl messages¶

Message registry management commands

Usage:

owl messages [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

owl messages list¶

List and search message types

Usage:

owl messages list [OPTIONS] [MESSAGE_TYPES]...

Options:

Name	Type	Description	Default
`--domain`, `-d`	text	Filter by domain (e.g., 'desktop')	None
`--search`, `-s`	text	Search message types by pattern	None
`--output-format`	text	Output format: table, json, yaml	`table`
`--verbose`, `-v`	boolean	Show detailed information	`False`
`--case-sensitive`, `-c`	boolean	Case sensitive search	`False`
`--limit`, `-l`	integer	Limit number of results	`50`
`--help`	boolean	Show this message and exit.	`False`

owl messages show¶

Show detailed information about a specific message type

Usage:

owl messages show [OPTIONS] MESSAGE_TYPE

Options:

Name	Type	Description	Default
`--output-format`	text	Output format: rich, json, schema	`rich`
`--example`, `-e`	boolean	Show usage example	`False`
`--help`	boolean	Show this message and exit.	`False`

owl messages validate¶

Validate message registry and definitions

Usage:

owl messages validate [OPTIONS]

Options:

Name	Type	Description	Default
`--verbose`, `-v`	boolean	Show detailed validation results	`False`
`--help`	boolean	Show this message and exit.	`False`

Common Workflows¶

# Record and analyze data
ocap my-session
owl mcap info my-session.mcap
owl mcap convert my-session.mcap

# Environment management
owl env list
owl env validate desktop

# Data processing
owl mcap info *.mcap
owl video probe session.mkv

Getting Help¶

owl --help                              # General help
owl mcap --help                         # Command group help
owl mcap info --help                    # Specific command help

Installation Guide - Installing OWA and CLI tools
Recording Data - Creating MCAP files with ocap
Exploring Data - Data analysis workflows
Environment Guide - Understanding environment plugins
Custom Messages - Creating custom message types

OWA CLI (owl) - Command Line Tools¶

Installation¶

Quick Start¶

Command Groups¶

📁 MCAP Commands (owl mcap)¶

🔌 Environment Commands (owl env)¶

📋 Message Commands (owl messages)¶

🎥 Video Commands (owl video)¶

Complete Command Reference¶

owl¶

owl env¶

owl env docs¶

owl env list¶

owl env search¶

owl env stats¶

owl env validate¶

owl mcap¶

owl mcap cat¶

owl mcap convert¶

owl mcap convert-overlay¶

owl mcap info¶

owl mcap migrate¶

owl mcap migrate cleanup¶

owl mcap migrate rollback¶

owl mcap migrate run¶

owl mcap rename-uri¶

owl mcap sanitize¶

owl messages¶

owl messages list¶

owl messages show¶

owl messages validate¶

Common Workflows¶

Getting Help¶

Related Documentation¶

OWA CLI (`owl`) - Command Line Tools¶

📁 MCAP Commands (`owl mcap`)¶

🔌 Environment Commands (`owl env`)¶

📋 Message Commands (`owl messages`)¶

🎥 Video Commands (`owl video`)¶