Scripting Reference

Overview
Basics
Settings
Command Reference
Variables
CLI Flags
Examples

Overview

QuikGIF scripts are line-oriented text files that automate multi-step GIF demo creation. Each line is a command with arguments. Scripts are executed with the quikgif script command:

$ quikgif script demo.qgif

Scripts can open applications, capture windows, simulate keyboard and mouse input, apply visual effects, and render the result as an optimized GIF -- all from a single .qgif file.

Basics

Comments -- Lines starting with # are ignored. Inline comments with # are also supported.
Variables -- Defined with as $name in capture-window and run commands. Referenced as $name, indexed as $name[N]. String interpolation: "hello $name".
Strings -- Quoted with double quotes. Supports \n, \t, \\, \" escape sequences.
Numbers -- Integer or decimal literals (e.g., 30, 0.5).

        # This is a comment
        set fps 30          # Inline comment
        open "Terminal"
        capture-window app "Terminal" as $term
        record $term duration 5 continue
        type "echo hello" enter
        remain
        render
      

Settings

Configure script behavior with set <key> <value>. Settings apply from the point they are declared.

Setting	Type	Default	Description
`fps`	int	`30`	Recording frame rate (12, 24, 30, 60)
`output`	string	`output.gif`	Output file path
`max-width`	int	`800`	Maximum GIF width in pixels
`loop-count`	int	`0`	GIF loop count (0 = infinite, 1 = once, 3 = three)
`transition`	float	`0.3`	Crossfade duration between segments (seconds)
`show-cursor`	bool	`true`	Show system cursor in recording
`cursor-smoothing`	bool	`false`	Enable cursor path smoothing
`click-indicators`	bool	`false`	Show visual click indicators
`type-smoothing`	bool	`false`	Smooth keystroke timing
`idle-strategy`	string	(disabled)	Idle frame handling: `fade`, `cut`, or `ramp`
`idle-threshold`	float	`2.0`	Seconds of inactivity before idle strategy applies
`include-title-bar`	bool	`false`	Keep real window title bar in output (overrides faux-title-bar)
`title-bar-height`	int	`28`	Points to paint over (use `52` for Terminal.app with tabs)
`faux-title-bar`	bool	`true`	Paint synthetic macOS title bar over window captures (`false` = crop instead)
`faux-title-bar-title`	string	(empty)	Text shown centered in faux title bar
`palette-strategy`	string	`auto`	GIF palette: `auto`, `global`, or `perFrame`
`cleanup`	bool	`true`	Close script-opened windows after render
`strict`	bool	`true`	Fail on non-zero shell command exit codes
`run-timeout`	float	`30`	Shell command timeout in seconds

Boolean settings use true/false string values.

Command Reference

Window Management

`open <app>`

Open an application and create a new window.

open "Terminal" open "Finder"

`focus <app>`

Bring an application's window to the front.

focus "Terminal"

`capture-window app <name> as $var`
`capture-window id <windowID> as $var`

Capture a window reference for recording. The as $var binding is optional.

capture-window app "Terminal" as $term capture-window id 12345 as $win

`resize <width> <height>`

Resize the target window (captured or recording) to the given dimensions.

resize 800 600

`clear`

Send Cmd+K to the target window (clears Terminal, works in many apps).

clear

Recording

`record $window [duration <seconds>] [continue]`

Start recording a window. Without duration, records until stop or next record. Without continue, blocks for the full duration. With continue, execution continues while recording runs in the background.

        record $term duration 10 continue
        # ... commands execute while recording ...
        remain
      

`record region <x> <y> <w> <h> [duration <seconds>] [continue]`

Record an absolute screen region by coordinates (in points). No window selection needed — captures everything visible in the rectangle. Useful for headless automation.

record region 100 200 800 600 duration 5 # Records a 800×600 region starting at screen position (100, 200)

`record $window crop <x> <y> <w> <h> [duration <seconds>] [continue]`

Record a sub-region of a window. Coordinates are relative to the window's content area (below the title bar). Captures only that window's content regardless of Z-order or focus.

record $term crop 0 0 400 300 duration 3 continue # Records the top-left 400×300 area of the Terminal window

`stop`

Stop the active recording.

stop

`remain`

Wait for the remaining duration of the current record ... duration N continue block.

        record $term duration 8 continue
        type "hello" enter
        wait 1.0
        remain   # waits for remaining ~6.9s
      

`render`

Stop any active recording and immediately render the GIF. If omitted, rendering happens automatically at script end.

render

Input Simulation

`type <text> [enter] [delay <seconds>]`

Simulate typing text. enter presses Return after typing. delay sets per-character delay (default 0.05s).

type "ls -la" enter type "Hello, world!" delay 0.08

`click [<x> <y>] [right]`

Simulate a mouse click. Without coordinates, clicks at the current cursor position.

        click 200 300
        click 100 200 right
        click
      

`move <x> <y> [duration <seconds>]`

Smoothly move the cursor to coordinates (default duration 0.3s).

move 400 250 duration 0.5

`cursor <x> <y>`

Instantly set cursor position (no animation).

cursor 100 100

`scroll <direction> [<ticks>]`

Simulate scroll wheel. Direction: up, down, left, right. Default 3 ticks.

scroll down 5 scroll up

`key <keyspec>`

Simulate a key press. Modifiers joined with +.

        key enter
        key cmd+c
        key shift+tab
        key cmd+shift+s
      

Timing

`wait <seconds>`

Pause execution for a number of seconds.

wait 1.5

`wait-for-idle <seconds>`

Wait until screen content stabilizes (no new frames for ~400ms) or until the timeout.

wait-for-idle 5.0

Shell Commands

`run <command> [as $var]`

Execute a shell command via /bin/sh -c. Optionally capture output lines to a variable.

Always sets $_exitcode to the command's exit code. If as $var is used and the command writes to stderr, $var_stderr is also set.

In strict mode (default), a non-zero exit code throws an error. Disable with set strict false.

        run "echo hello"
        run "ls -la" as $output
        set strict false
        run "might-fail" as $result
        # $result has stdout, $result_stderr has stderr, $_exitcode has exit code
      

Visual Effects

`spotlight stdout $var[N] duration <seconds>`
`spotlight region <x> <y> <width> <height> duration <seconds>`

Highlight a region of the recording. stdout mode estimates line position from captured output.

        run "ls -la" as $output
        spotlight stdout $output[0] duration 2.0
        spotlight region 100 200 300 50 duration 1.5
      

`spotlight-shift <target> duration <seconds>`

Animate the spotlight from its previous position to a new target.

spotlight stdout $output[0] duration 2.0 spotlight-shift stdout $output[2] duration 0.5

`clear-fx`

Remove all active visual effects.

clear-fx

Variables

Variables are created by capture-window ... as $name and run ... as $name.

Variable	Set By	Type	Description
`$name`	`capture-window`	Window ID	The captured window's numeric ID
`$name`	`run`	Lines	Stdout split into lines
`$name[N]`	`run`	String	Nth line of captured output (0-indexed)
`$name_stderr`	`run`	String	Stderr output (set when non-empty)
`$_exitcode`	`run`	String	Exit code of the last `run` command

Variable interpolation in strings: "File: $name" substitutes the variable's value.

CLI Flags

        $ quikgif script demo.qgif           # Execute a script
        $ quikgif script --dry-run demo.qgif  # Validate without executing
        $ quikgif script --list-commands        # Show all available commands
        $ quikgif script -q demo.qgif        # Quiet mode (suppress progress)
      

--dry-run performs static analysis:

Checks syntax validity
Warns about undefined variables used in record
Warns about missing record commands
Detects unreachable code after render

Examples

See the examples/ directory for complete scripts:

hello.qgif -- Basic Terminal recording
git-workflow.qgif -- Multi-command git demo
multi-window.qgif -- Multi-window recording with segment stitching
spotlight-demo.qgif -- Spotlight effects and stdout highlighting

Scripting Reference

Contents

Overview

Basics

Settings

Command Reference

Window Management

open <app>

focus <app>

capture-window app <name> as $varcapture-window id <windowID> as $var

resize <width> <height>