Skip to main content

Scripting Overview

QuikGIF scripts (.qgif files) are a line-oriented DSL for creating multi-step GIF demos. Each line is a command that the engine executes sequentially: opening apps, recording windows, simulating input, applying visual effects, and rendering the final GIF.

Running a Script​

quikgif script demo.qgif

The engine parses the script, executes each instruction in order, and writes the output GIF to the path specified by set output.

Preview Mode​

Render a quick low-resolution preview to iterate faster:

quikgif script demo.qgif --preview

Preview mode uses 10fps, 400px max width, and a global color palette. The output is written to /tmp/quikgif-preview-*.gif and opens automatically in Preview.app.

Dry-Run Validation​

Check a script for syntax errors and common issues without executing it:

quikgif script demo.qgif --dry-run

Dry-run performs static analysis including:

  • Syntax validation
  • Undefined variable detection
  • Missing record/render warnings
  • Unreachable code after render
  • Invalid set pace preset names

List Available Commands​

quikgif script --list-commands

Prints all 24 commands with their syntax. The file argument is optional when using this flag.

Basic Structure​

A .qgif script typically follows this pattern:

# 1. Configure settings
set fps 30
set output "demo.gif"
set max-width 800

# 2. Open and prepare a window
open "Terminal"
capture-window app "Terminal" as $term
resize 800 400
clear

# 3. Record while performing actions
record $term duration 5 continue
type "echo Hello from QuikGIF!" enter
wait 1.0
remain

# 4. Render the GIF
render

Comments​

Lines starting with # are ignored:

# This is a comment
set fps 30  # Inline comments are NOT supported
warning

Only full-line comments are supported. Text after # on a command line is not treated as a comment.

Key Concepts​

Recording Segments​

A script can record multiple segments. Each record ... remain or record ... stop block captures one segment. When render is called, all segments are stitched together with optional crossfade transitions (controlled by set transition).

Blocking vs Non-Blocking Recording​

  • record $win duration 5 -- blocks for 5 seconds, then continues
  • record $win duration 5 continue -- starts recording and immediately executes subsequent commands. Use remain to wait for the remaining duration.

Variables​

Commands like capture-window and run create variables that can be referenced later:

capture-window app "Terminal" as $term
run "git log --oneline -3" as $log

# Use variables
record $term duration 3 continue
spotlight stdout $log[0] duration 2

See the Variables page for full details.