OWA CLI (owl) - Command Line Tools¶
The owl command provides comprehensive tools for working with OWA data, environments, and message types.
Installation¶
The CLI is included with the owa-cli package:
After installation, the owl command becomes available in your terminal.
CLI Reference¶
owl¶
owl - Open World agents cLi - Tools for managing OWA data and environments
Usage:
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:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
owl env docs-stats¶
Show documentation statistics for plugins.
This is a helper command for development and analysis.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--by-type |
boolean | Group statistics by component type | False |
--help |
boolean | Show this message and exit. | False |
owl env find¶
Quick search - find components by pattern (alias for 'search').
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
owl env health¶
Perform a health check on the plugin ecosystem.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
owl env list¶
List discovered plugins and their components with enhanced filtering and display options.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--namespace, -n |
text | Filter plugins by namespace | None |
--type, -t |
text | Type of components to list (callables/listeners/runnables) | None |
--search, -s |
text | Search components by name pattern | None |
--components, -c |
boolean | Show individual components | False |
--details, -d |
boolean | Show detailed component information | False |
--table |
boolean | Display results in table format | False |
--sort |
text | Sort by: namespace, name, type | namespace |
--help |
boolean | Show this message and exit. | False |
owl env ls¶
Quick list - show plugins or components in a namespace (alias for 'list').
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
owl env namespaces¶
List all available namespaces.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
owl env search¶
Search for components across all plugins using pattern matching.
Usage:
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 show¶
Show detailed information about a plugin with enhanced filtering and inspection options.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--components, -c |
boolean | Show individual components | False |
--type, -t |
text | Filter by component type | None |
--search, -s |
text | Search components by name pattern | None |
--details, -d |
boolean | Show import paths and load status | False |
--table |
boolean | Display components in table format | False |
--inspect, -i |
text | Inspect specific component (show docstring/signature) | None |
--help |
boolean | Show this message and exit. | False |
owl env stats¶
Show comprehensive statistics about the plugin ecosystem.
Usage:
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 |
--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:
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 env validate-docs¶
Validate plugin documentation with proper exit codes for CI/CD integration.
This command serves as a test utility that can be integrated into CI/CD pipelines, ensuring consistent documentation quality across all plugins.
Features: - Per-component quality grading (GOOD/ACCEPTABLE/POOR) - Per-plugin quality thresholds (PASS/WARN/FAIL) - Skip quality check support (@skip-quality-check in docstrings) - Flexible threshold configuration
Exit codes: - 0: All validations passed - 1: Documentation issues found (warnings or failures) - 2: Command error (invalid arguments, plugin not found, etc.)
Usage:
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 |
--format |
text | Output format: text or json | text |
--help |
boolean | Show this message and exit. | False |
owl mcap¶
MCAP file management commands
Usage:
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:
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:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--topics |
text | Comma-separated list of topics to include in the subtitle file | window,keyboard,mouse,keyboard/state |
--help |
boolean | Show this message and exit. | False |
owl mcap info¶
Display information about the .mcap file.
Usage:
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:
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:
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:
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:
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 record¶
Record screen, keyboard, mouse, and window events to an .mcap and .mkv file.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--record-audio / --no-record-audio |
boolean | Whether to record audio | True |
--record-video / --no-record-video |
boolean | Whether to record video | True |
--record-timestamp / --no-record-timestamp |
boolean | Whether to record timestamp | True |
--show-cursor / --no-show-cursor |
boolean | Whether to show the cursor in the capture | True |
--fps |
float | The frame rate of the video. Default is 60 fps. | 60.0 |
--window-name |
text | The name of the window to capture, substring of window name is supported | None |
--monitor-idx |
integer | The index of the monitor to capture | None |
--width |
integer | The width of the video. If None, the width will be determined by the source. | None |
--height |
integer | The height of the video. If None, the height will be determined by the source. | None |
--additional-args |
text | Additional arguments to pass to the pipeline. For detail, see https://gstreamer.freedesktop.org/documentation/d3d11/d3d11screencapturesrc.html | None |
--start-after |
float | Delay recording start by this many seconds. Shows countdown during delay. | None |
--stop-after |
float | Automatically stop recording after this many seconds from start. | None |
--health-check-interval |
float | Interval in seconds for checking resource health. Set to 0 to disable. | 5.0 |
--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
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--keep-window |
text | Window name to keep events for | _required |
--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:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
owl messages list¶
List all available message types
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--domain, -d |
text | Filter by domain (e.g., 'desktop') | None |
--format, -f |
text | Output format: table, json, yaml | table |
--verbose, -v |
boolean | Show detailed information | False |
--help |
boolean | Show this message and exit. | False |
owl messages show¶
Show details about a specific message type
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--format, -f |
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:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--verbose, -v |
boolean | Show detailed validation results | False |
--fix |
boolean | Attempt to fix validation issues | False |
--help |
boolean | Show this message and exit. | False |