Commands

All 25 commands available in .qgif scripts, grouped by category. The set command has its own Settings page.

Each entry lists a synopsis, an arguments table, an example, and the errors the parser can raise for that command. Parse errors report the exact line and column with a ^ caret under the offending token (see Dry-Run Validation).

Argument types

<number> accepts an integer or decimal. <string> is a quoted literal ("text") or a bare word. $var is a variable reference; $var[N] indexes a captured output line. Coordinates and sizes are in screen points.

---

Window Management

open

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

Argument	Type	Required	Default	Description
app name	<string>	yes	—	Application name to launch

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

Errors

• Missing argument — no app name supplied.

focus

Bring an application to the front.

Argument	Type	Required	Default	Description
app name	<string>	yes	—	Application to activate

focus "Terminal"

Errors

• Missing argument — no app name supplied.

capture-window

Capture a window reference and bind it to a variable. Required before recording a window. Target the window either by application name (app) or by numeric window ID (id).

Argument	Type	Required	Default	Description
app / id	keyword	yes	—	Selector type
target	<string> (app) or <number> (id)	yes	—	App name or window ID
as $var	binding	no	—	Bind the resolved window ID to a variable

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

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

Errors

• Missing argument — fewer than two tokens (no selector + target).
• Expected 'app' or 'id' — selector keyword missing or unrecognized.
• 'as' must be followed by $variable — as is present but not followed by a $variable.

resize

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

Argument	Type	Required	Default	Description
width	<number>	yes	—	New width in points
height	<number>	yes	—	New height in points

resize 800 400

Errors

• Missing argument — width or height not supplied.

clear

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

clear

Errors

• None at parse time.

---

Recording

record

Start recording. Three target forms: a captured window, a window sub-region (crop), or an absolute screen region (region).

Argument	Type	Required	Default	Description
target	$var / region / $var crop	yes	—	What to capture
x y w h	<number> ×4	with region/crop	—	Region or crop rectangle
duration <seconds>	<number>	no	unbounded	Recording length
continue	flag	no	off	Non-blocking mode
audio [system|mic|both]	flag	no	off	Capture audio (MP4 output only)

Record a window:

record $term duration 5
record $term duration 5 continue

Record with audio (MP4 only): add the audio flag to capture sound into an MP4. A bare audio captures system audio; audio mic records the microphone (prompts for permission once; denial degrades to no audio); audio both mixes system and microphone into a single stereo track so every player hears both. Audio is ignored for GIF/WebP/APNG output, and requires set format mp4 — a .mp4 output filename alone does not select MP4.

set format mp4
set output "demo.mp4"
record $term duration 5 audio system
record $term duration 5 audio both

Record a window sub-region (crop): coordinates are relative to the window's content area (below the title bar).

record $term crop 0 0 400 300 duration 5 continue

Record a screen region: coordinates are absolute screen coordinates.

record region 100 200 800 600 duration 5 continue

Without continue, recording blocks for the full duration. With continue, the engine keeps executing subsequent commands while recording — pair it with remain.

Errors

• Missing argument — no target, or region/crop without all four x y w h values.
• Missing argument (duration value) — duration keyword not followed by a number.

stop

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

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

Errors

• None at parse time.

remain

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

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)

Errors

• None at parse time.

render

Stop any active recording and encode all recorded segments into the final GIF. Typically the last command in a script. Takes no arguments.

render

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

Errors

• None at parse time.

---

Input Simulation

type

Simulate typing text with human-like pacing.

Argument	Type	Required	Default	Description
text	<string>	yes	—	Text to type
enter	flag	no	off	Press Enter after typing
delay <seconds>	<number>	no	0.05	Per-character delay

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

info

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

Errors

• Missing argument — no text supplied.

click

Mouse click at coordinates or at the current cursor position.

Argument	Type	Required	Default	Description
x	<number>	no	current	X coordinate
y	<number>	no	current	Y coordinate
right	flag	no	left	Use the right mouse button

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

Coordinates are optional — supply both x and y, or neither.

Errors

• None at parse time.

move

Smooth cursor movement to a position.

Argument	Type	Required	Default	Description
x	<number>	yes	—	Target X coordinate
y	<number>	yes	—	Target Y coordinate
duration <seconds>	<number>	no	0.3	Animation duration

move 400 250 duration 0.5

Errors

• Missing argument — x or y not supplied.

cursor

Instantly set the cursor position (no animation).

Argument	Type	Required	Default	Description
x	<number>	yes	—	X coordinate
y	<number>	yes	—	Y coordinate

cursor 200 300

Errors

• Missing argument — x or y not supplied.

scroll

Scroll at the current cursor position.

Argument	Type	Required	Default	Description
direction	up / down / left / right	yes	—	Scroll direction
ticks	<number>	no	3	Number of scroll ticks

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

Errors

• Missing argument — no direction supplied.
• Invalid value — direction is not one of up, down, left, right.

key

Press a key with optional modifiers. Combine modifiers with +.

Argument	Type	Required	Default	Description
key spec	[mod+...]key	yes	—	Key name, optionally prefixed with 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

Errors

• Missing argument — no key name supplied.

---

Timing

wait

Pause execution for a number of seconds.

Argument	Type	Required	Default	Description
seconds	<number>	yes	—	Seconds to pause

wait 1.5
wait 0.3

Errors

• Missing argument — no duration supplied.

wait-for-idle

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

Argument	Type	Required	Default	Description
seconds	<number>	yes	—	Idle window to wait for

wait-for-idle 2.0

Errors

• Missing argument — no duration supplied.

---

Shell Commands

run

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

Argument	Type	Required	Default	Description
command	<string>	yes	—	Shell command to run
as $var	binding	no	—	Capture stdout lines into 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 at runtime:

• 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).

Errors

• Missing argument — no command supplied.

---

Visual Effects

spotlight

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

Argument	Type	Required	Default	Description
stdout / region	keyword	yes	—	Target type
$var[N]	indexed variable	with stdout	—	Captured output line to highlight
x y width height	<number> ×4	with region	—	Region rectangle
duration <seconds>	<number>	no	2.0	How long the spotlight holds

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

Errors

• Missing argument — no target, or region without all four values.
• Expected target type — first token is not a keyword.
• Expected $variable[N] for stdout target — stdout not followed by an indexed variable.
• Invalid value — target type is neither stdout nor region.

spotlight-shift

Animate the spotlight from its current position to a new target. Same arguments and errors as spotlight.

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

clear-fx

Remove all active visual effects. Takes no arguments.

clear-fx

Errors

• None at parse time.

---

Canvas

set-background

Composite every frame over a solid background color. Transparent pixels — rounded window corners, or alpha in APNG/WebP output — show the chosen color instead of black. Applied as the base layer during rendering, so overlays (spotlights, title bars) draw on top.

Argument	Type	Required	Default	Description
color	keyword	no	—	Optional leading keyword
hex	<string>	yes	—	6-digit hex color (#RRGGBB or RRGGBB)

set-background "#FF0000"        # quotes protect # from comment stripping
set-background FF0000           # bare 6-digit hex also works
set-background color "#0d1117"  # optional 'color' keyword

note

Quote the hex value when it starts with #. Outside quotes, # begins a comment, so set-background #FF0000 would drop the color. Bare 6-digit hex (FF0000) needs no quotes. Invalid values fall back to black.

This is equivalent to the set background setting.

Errors

• Missing argument — no hex color supplied.

---

Title Cards

intro

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

Argument	Type	Required	Default	Description
title	<string>	yes	—	Title text
subtitle <text>	<string>	no	—	Optional subtitle
duration <seconds>	<number>	yes	—	How long the card displays

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

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

Errors

• Missing argument (title text) — no title supplied.
• Missing argument (subtitle text) — subtitle keyword with no following text.
• Missing argument (duration value) — duration keyword not followed by a number.
• Missing argument (duration) — no duration provided (it is required).

outro

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

Argument	Type	Required	Default	Description
title	<string>	yes	—	Title text
subtitle <text>	<string>	no	—	Optional subtitle
duration <seconds>	<number>	yes	—	How long the card displays

outro "Thanks for watching!" duration 1.5

Errors

• Same as intro: missing title, dangling subtitle, missing/empty duration.

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.

---

Dialogs

dismiss-dialog

Dismiss an unexpected dialog or sheet that appears during a recording (e.g. a "Save changes?" prompt). Both arguments are optional: with no arguments the engine dismisses the frontmost dialog; supply app to scope to a specific application and/or button to click a named button.

Argument	Type	Required	Default	Description
app <name>	<string>	no	frontmost	Scope dismissal to this application
button <label>	<string>	no	default button	Click the button with this label

dismiss-dialog                                  # Dismiss the frontmost dialog
dismiss-dialog button "Don't Save"              # Click a specific button
dismiss-dialog app "TextEdit" button "Cancel"   # Scope to an app and button

Errors

• Expected 'app' or 'button' keyword — a non-keyword token was found where a keyword was expected.
• Missing argument (app name) — app keyword with no following name.
• Missing argument (button label) — button keyword with no following label.
• Unexpected keyword '<kw>' — a keyword other than app or button was used.

click-button-in-dialog

Click a named button in the frontmost dialog or sheet to proceed — e.g. clicking OK, Save, or Continue to confirm an action. This is the affirmative counterpart to dismiss-dialog, which cancels/dismisses (sending Escape). The button argument is required; app is optional and defaults to the active or last-captured application.

It looks for the button in a sheet attached to the app's front window, then in the front window itself (covering standalone dialog windows such as open/save panels and app-modal alerts). If no dialog or matching button is found, the command prints a warning rather than reporting a click that never happened.

Argument	Type	Required	Default	Description
app <name>	<string>	no	active app	Scope the search to this application
button <label>	<string>	yes	—	Click the button with this label

click-button-in-dialog button "OK"                       # Click OK in the frontmost dialog
click-button-in-dialog app "TextEdit" button "Save"      # Scope to an app, click Save

Accessibility permission

This command drives the dialog via macOS System Events, which requires Accessibility permission for the quikgif CLI. Grant it under System Settings → Privacy & Security → Accessibility. Without it, the command prints a one-line warning and no-ops rather than failing.

Errors

• Expected 'app' or 'button' keyword — a non-keyword token was found where a keyword was expected.
• Missing argument (button label) — the required button keyword/label was omitted.
• Missing argument (app name) — app keyword with no following name.
• Unexpected keyword '<kw>' — a keyword other than app or button was used.
• Duplicate '<kw>' keyword — app or button was specified more than once.