Skip to content

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, subtitle, migrate, sanitize

owl mcap info session.mcap              # File information
owl mcap cat session.mcap --n 10        # View messages
owl mcap subtitle session.mcap          # Generate subtitle file (.srt)

🔌 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]...

owl env

Environment plugin management commands

Usage:

owl env [OPTIONS] COMMAND [ARGS]...
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]
owl env list

List environment plugins and components.

Usage:

owl env list [OPTIONS] [namespaces]...

Search for components across all plugins using pattern matching.

Usage:

owl env search [OPTIONS] {pattern}
owl env stats

Show comprehensive statistics about the plugin ecosystem.

Usage:

owl env stats [OPTIONS]
owl env validate

Validate a plugin specification from YAML file or entry point.

This command can validate plugin specifications in two ways:

  1. From YAML files: owl env validate ./plugin.yaml
  2. 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}

owl mcap

MCAP file management commands

Usage:

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

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

Usage:

owl mcap cat [OPTIONS] {mcap_path}
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}...
owl mcap migrate

MCAP migration commands with rollback and cleanup support.

Usage:

owl mcap migrate [OPTIONS] COMMAND [ARGS]...
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//.mcap.backup" # Clean all backup files recursively under a specific directory owl mcap migrate cleanup file.mcap # Clean backup for specific MCAP file

Usage:

owl mcap migrate cleanup [OPTIONS] [patterns]...
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}...
owl mcap migrate run

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

Usage:

owl mcap migrate run [OPTIONS] {files}...
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}...
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}...
owl mcap subtitle

Generate subtitle file from MCAP recording for playback verification.

Usage:

owl mcap subtitle [OPTIONS] {input_file}
owl mcap trim

Trim mcap recording and referenced MKV files to a specific time range.

Usage:

owl mcap trim [OPTIONS] {input_mcap} {output_mcap}

owl messages

Message registry management commands

Usage:

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

List and search message types

Usage:

owl messages list [OPTIONS] [message_types]...
owl messages show

Show detailed information about a specific message type

Usage:

owl messages show [OPTIONS] {message_type}
owl messages validate

Validate message registry and definitions

Usage:

owl messages validate [OPTIONS]

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