/asciinema-tools:convert
Convert asciinema .cast recordings to clean .txt files. Supports single file and batch directory modes.
Arguments
Single File Mode
Argument Description
file
Path to .cast file
-o, --output
Output path (default: same dir)
--index
Create timestamp indexed version
--chunks
Split at 30s+ idle pauses
--dims
Preserve terminal dimensions
--analyze
Auto-run /analyze after conversion
Batch Mode
Argument Description
--batch
Enable batch mode for directory conversion
--source
Source directory (default: ~/asciinemalogs)
--output-dir
Output directory (default: ~/Downloads/cast-txt/)
--skip-existing
Skip files that already have .txt output (default: true)
Note: --batch and positional file are mutually exclusive.
Execution
Invoke the asciinema-converter skill with user-selected options.
Single File Skip Logic
-
If file provided → skip Phase 1 (file selection)
-
If options provided → skip Phase 2 (options)
-
If -o provided → skip Phase 3 (output location)
-
If --analyze provided → skip Phase 6 and auto-run analyze
Batch Mode Skip Logic
-
If --batch provided → skip Phases 1-3, enter batch phases (7-10)
-
If --source provided → skip Phase 7 (source selection)
-
If --output-dir provided → skip Phase 8 (output organization)
Single File Workflow
-
Preflight: Check asciinema convert command
-
Discovery: Find .cast files
-
Selection: AskUserQuestion for file
-
Options: AskUserQuestion for conversion options
-
Location: AskUserQuestion for output location
-
Execute: Run asciinema convert
-
Report: Display compression ratio
-
Next: AskUserQuestion for follow-up action
Batch Workflow
-
Preflight: Check asciinema convert command
-
Source: AskUserQuestion for source directory
-
Output: AskUserQuestion for output directory
-
Execute: Batch convert with progress reporting
-
Report: Display aggregate compression stats
-
Next: AskUserQuestion for follow-up action
Examples
Single file conversion
/asciinema-tools:convert ~/Downloads/session.cast
Batch mode with defaults
/asciinema-tools:convert --batch
Batch mode with custom paths
/asciinema-tools:convert --batch --source ~/Downloads --output-dir ~/cast-txt/
Batch mode, force re-convert existing
/asciinema-tools:convert --batch --skip-existing=false
Troubleshooting
Issue Cause Solution
asciinema not found asciinema not installed brew install asciinema
Convert command failed Corrupted .cast file Try asciinema cat file.cast first
No .cast files found Wrong directory Check --source path
Output not created Permission denied Check write permissions on output
File too large Long recording session Use --chunks to split at pauses