quipu #

Yet another terminal keyboard entry scripting tool – good for recording terminal demos with tools like asciinema.

Features #

• Script keyboard sequences for terminal demos
• Control typing speed and add natural jitter
• Support for special keys and modifier combinations (Ctrl, Alt, Shift)
• Works with terminal recording tools like asciinema

Install #

brew install waddie/brew/quipu

Or brew tap waddie/brew first, then install by name.

Build from source #

cargo install --path .

Or build from source:

git clone https://github.com/waddie/quipu.git
cd quipu
cargo build --release

Usage #

Create a script file (.qp extension) with your keyboard sequences:

@ speed:0.1
@ jitter:0.03

# This is a comment
$ echo "Hello from quipu!"<ret>

@ wait:1.0

$ ls -la<ret>

@ wait:0.5

$ # Type commands with special keys
$ vim example.txt<ret>
$ iHello World!<esc>:wq<ret>

Run the script:

quipu script.qp

Pass -q/--quiet to suppress the informational status messages. Pass -V/--version to print the version and exit.

Repeating an option is allowed; the last occurrence wins.

By default, quipu uses your current shell ($SHELL). To use a different shell:

quipu --shell /bin/bash script.qp

Or use the shell directive in your script:

@ shell:/bin/bash
$ echo "Running in: $SHELL"<ret>

Record with asciinema:

asciinema rec demo.cast -c "quipu script.qp"

Script Format #

Directives (@ lines) #

• @ speed:N - Set time between keystrokes in seconds (default: 0.1)
• @ jitter:N - Set random variation as fraction of speed (default: 0.0)
• @ wait:N - Pause for N seconds before continuing
• @ shell:PATH - Set shell to use (defaults to $SHELL, must come before any typing commands; a --shell CLI argument takes priority)
• @ size:COLS:ROWS - Set terminal size (default: 80x24, must come before any typing commands)
• @ capture:PATH - Capture the current screen to PATH, including escape codes. Consider a preceding wait or expect to allow the screen to settle.
• @ capture-text:PATH - Capture the current screen to PATH as plain text
• @ expect:TEXT - Wait until a line of the screen contains TEXT (everything after the colon, # included, with surrounding spaces trimmed). If it doesn't appear within the timeout, quipu stops, prints the screen, and exits with status 1.
• @ timeout:N - Set how long expect waits, in seconds (default: 10)

Numeric directive values must be non-negative.

Scripts as tests #

expect waits only as long as it has to, so a script can drive a terminal program and check what it shows without guessing at wait times. A failed expect makes quipu exit with status 1, which is all a test runner needs:

@ speed:0.01
@ timeout:5
$ hx example.clj<ret>
@ expect:NOR
$ :quit<ret>

Comments (# lines) #

Lines starting with # are ignored.

Typing ($ lines) #

Lines starting with $ are typed into the terminal:

$ echo "regular text"

Special Keys #

Use angle brackets for special keys:

Basic keys:

• <esc> - Escape
• <ret>, <return>, <enter> - Return/Enter
• <space> - Space
• <tab> - Tab
• <backspace>, <bs> - Backspace

Function keys:

• <F1> through <F12>

Arrow keys:

• <up>, <down>, <left>, <right>

Navigation:

• <home>, <end>
• <pageup>, <pagedown>
• <insert>, <delete>

Modifier Keys #

Use modifier prefixes with a dash:

• <C-x> or <Ctrl-x> - Ctrl+X
• <A-x> or <Alt-x> - Alt+X
• <S-x> or <Shift-x> - Shift+X
• <C-S-x> - Ctrl+Shift+X
• <S-tab> - Backtab

Examples:

$ <C-c>           # Send Ctrl-C
$ <C-d>           # Send Ctrl-D (EOF)
$ <A-f>           # Alt-F (forward word in bash)
$ <C-X><C-S>      # Ctrl-X Ctrl-S (save in emacs)

Escaping #

Use backslash to escape angle brackets:

$ echo "Literal \<angle\> brackets"

An unrecognized <...> sequence is a parse error, so unescaped angle bracket pairs must be escaped. A lone < with no > later on the line (e.g. shell redirection cat < file) is typed literally.

License #

GNU AGPL v3 - See LICENSE.md