Skip to main content

Commands

All 24 commands available in .qgif scripts, grouped by category.

Window Management​

open​

Launch an application and create a new window, even if the app is already running.

open "Terminal"
open "Finder"
open "Safari"

focus​

Bring an application to the front.

focus "Terminal"

capture-window​

Capture a window reference and bind it to a variable. Required before recording a window.

By application name:

capture-window app "Terminal" as $term

By window ID:

capture-window id 12345 as $win

The variable stores the window ID and can be used with record.

resize​

Resize the target window (the last captured or focused window).

resize 800 400

clear​

Send Cmd+K to the target app to clear the terminal or application content.

clear

Recording​

record​

Start recording a window. Three variants:

Record a window:

record $term duration 5
record $term duration 5 continue

Record a window sub-region (crop):

record $term crop 0 0 400 300 duration 5 continue

Crop coordinates are relative to the window's content area (below the title bar).

Record a screen region:

record region 100 200 800 600 duration 5 continue

Region coordinates are absolute screen coordinates.

Options:

  • duration <seconds> -- how long to record
  • continue -- non-blocking mode: the engine continues executing subsequent commands while recording. Without continue, recording blocks for the full duration.

stop​

Manually stop the active recording. Typically not needed when using duration.

record $term continue
type "echo hello" enter
wait 2
stop

remain​

Wait for the remaining duration of a record ... continue block. Place this after all the commands you want to execute during the recording.

record $term duration 5 continue
type "echo hello" enter    # Executes immediately
wait 1.0                    # Wait 1 second
remain                      # Wait for remaining time (up to 5s total)

render​

Stop any active recording and encode all recorded segments into the final GIF. This is typically the last command in a script.

render

If multiple segments were recorded, they are stitched together with crossfade transitions (controlled by set transition).

Input Simulation​

type​

Simulate typing text with human-like pacing.

type "echo Hello World" enter
type "ls -la" enter delay 0.08
type "some text without enter"

Options:

  • enter -- press Enter after typing
  • delay <seconds> -- per-character delay (default: 0.05s, or as set by set typing-delay)
info

The delay keyword on the command sets an explicit per-character delay for that specific type command. The global set typing-delay setting only applies when no explicit delay is provided.

click​

Mouse click at coordinates or at the current cursor position.

click                    # Click at current position
click 200 300            # Left-click at (200, 300)
click 200 300 right      # Right-click at (200, 300)

move​

Smooth cursor movement to a position.

move 400 250 duration 0.5

The duration option controls animation speed (default: 0.3s).

cursor​

Instantly set the cursor position (no animation).

cursor 200 300

scroll​

Scroll at the current cursor position.

scroll down 5
scroll up 3
scroll left 2
scroll right 2

Directions: up, down, left, right. The second argument is the number of ticks (default: 3).

key​

Press a key with optional modifiers. Use + to combine modifiers.

key enter
key cmd+c
key shift+tab
key ctrl+alt+delete
key f5

Supported keys: enter/return, tab, space, delete/backspace, escape/esc, up, down, left, right, home, end, pageup, pagedown, f1-f12, a-z

Supported modifiers: cmd/command, shift, alt/option, ctrl/control

Timing​

wait​

Pause execution for a number of seconds.

wait 1.5
wait 0.3

wait-for-idle​

Wait until the screen stabilizes (no significant pixel changes) for the specified duration.

wait-for-idle 2.0

Shell Commands​

run​

Execute a shell command. Optionally capture output to a variable.

run "echo hello"
run "git log --oneline -5" as $log
run "cat /etc/hosts" as $hosts

Variable behavior:

  • $_exitcode is set after every run command
  • $var_stderr is set when stderr is non-empty
  • Output lines are accessible via indexing: $log[0], $log[1], etc.

Error handling:

  • In strict mode (default: on), a non-zero exit code throws an error
  • Disable with set strict false
  • Commands time out after set run-timeout seconds (default: 30)

Visual Effects​

spotlight​

Highlight a region of the recording with a spotlight effect (dims everything else).

Highlight a captured output line:

run "cat /etc/hosts" as $hosts
spotlight stdout $hosts[0] duration 2.0

Highlight a screen region:

spotlight region 50 80 400 60 duration 2.0

spotlight-shift​

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

spotlight stdout $hosts[0] duration 2.0
spotlight-shift stdout $hosts[2] duration 1.5

clear-fx​

Remove all active visual effects.

clear-fx

Title Cards​

intro​

Add an intro title card at the beginning of the GIF. Rendered after all segments are stitched.

intro "My Demo" subtitle "Using QuikGIF" duration 2
intro "Simple Title" duration 1.5

Options:

  • subtitle "text" -- optional subtitle text
  • duration <seconds> -- required, how long the title card displays

Title card appearance is controlled by settings: intro-bg, intro-fg, intro-subtitle-fg, intro-font-size.

outro​

Add an outro title card at the end of the GIF.

outro "Thanks for watching!" duration 1.5

Options:

  • duration <seconds> -- required, how long the title card displays
tip

Place intro before any record commands and outro before render. The title cards are injected into the final GIF during the render phase, not during recording.