quikgif record

Record a window or screen region as a GIF.

quikgif record [options]

Target Selection

Specify what to record. If no target is given, an interactive window picker is shown.

Flag	Type	Description
--window	UInt32	Window ID to capture (use list-windows to find IDs)
--app	String	Filter/auto-select by app name. Auto-selects if only one window matches
--region	String	Screen region: x,y,w,h (origin+size) or x1,y1:x2,y2 (corners) in points
--crop	String	Window sub-region: x,y,w,h or x1,y1:x2,y2 relative to content area. Requires --window or --app
--simulator	String	Capture the iOS Simulator's device framebuffer at native resolution. Takes a UDID or device name; omit the value to use the only booted simulator. [Pro]
--simulator-auto	Bool	Shorthand for --simulator with no device argument (the only booted simulator)
--device	String	Record the screen of an iPhone or iPad connected by cable. Takes a name or ID from list-devices
--device-auto	Bool	Shorthand for --device with no argument (the only connected device)

info

--region and --crop are mutually exclusive. --region captures a screen area directly and cannot be combined with --window or --app. Use --crop to capture a sub-region of a specific window.

Device Capture

--device (or --device-auto) records the screen of a real iPhone or iPad connected to this Mac by cable, the same way QuickTime Player's movie recording does. Connect the device, unlock it, and tap Trust if it asks. Run quikgif list-devices to see what is connected.

quikgif record --device-auto --duration 10 -o app-demo.gif
quikgif record --device "My iPhone" --duration 10 --format mp4 -o app-demo.mp4

macOS treats a device screen as a camera, so the first recording asks for camera access for your terminal app (System Settings > Privacy & Security > Camera). Frames are downscaled as they arrive (--max-width, default 800) or fitted with --size. If you rotate the device mid-recording, later frames are fitted inside the first frame's size with black bars rather than stretched.

Like --simulator, it cannot be combined with --window, --app, --region, --crop, the title-bar flags, or the input-event effects. --audio is rejected: the device's sound is not recorded yet.

Simulator Capture

--simulator (or --simulator-auto) records the iOS Simulator's device framebuffer directly through simctl - not the Simulator window that macOS composites on screen. This is the only way to produce a native-resolution iOS asset (e.g. 1320×2868 for an iPhone 16 Pro Max), since the Simulator window itself is scaled down for on-screen display (~494×1054 at typical zoom). It is mutually exclusive with --window, --app, --region, and --crop.

quikgif record --simulator-auto --duration 5 --format mp4 --full-resolution -o preview.mp4

Because simctl captures a raw device recording with no window chrome, several flags do not apply and are rejected at validation time: --include-title-bar / --no-include-title-bar, --faux-title-bar, --cursor-smoothing, --click-indicators, --keystroke-badges, --zoom-cursor, and --type-smoothing (there are no captured input events to visualize).

--audio is rejected with --simulator

simctl captures no audio at all - there is no API to enable it. Combining --audio with --simulator fails validation with a clear error rather than silently producing a silent MP4. If you need audio alongside a Simulator demo, record the Simulator's on-screen window instead (--app Simulator), which trades away native resolution for the ability to capture system or microphone audio.

Scripted taps steal focus

Recording the Simulator on its own (no tap commands) is unobtrusive - it runs in the background like any other capture. But a .qgif script that issues tap commands is a different story: QuikGIF has no touch-injection API for the Simulator, so a tap is delivered as a synthesized mouse click, and a click always goes to whichever window is frontmost on macOS. To aim a tap correctly, QuikGIF must raise the Simulator window before every tap - which takes over your screen for the duration of the script. Do not use the machine while a tap-driven Simulator script is running.

If QuikGIF cannot raise the Simulator window, or cannot confidently calibrate the device screen to macOS screen points, the script fails loudly and delivers zero clicks rather than guessing. This is deliberate: a click it cannot aim precisely is a click that could land on a button in whatever app happens to be in front. See tap in the scripting reference for the full behavior.

Recording Parameters

Flag	Type	Default	Description
--duration	Double	--	Auto-stop after N seconds. Without this, stop with Ctrl+C
--fps	Int	30	Frame rate
--show-cursor / --no-show-cursor	Bool	true	Show cursor in capture
--include-title-bar / --no-include-title-bar	Bool	false	Include window title bar

Output

Flag	Type	Default	Description
-o, --output	String	recording.gif	Output file path
--max-width	Int	800	Max output width in pixels
--full-resolution	Bool	false	Use native resolution (ignores --max-width)
--size	String	--	Exact output size as WxH in pixels, e.g. 1320x2868. Mutually exclusive with --max-width. [Pro]
--fit	String	contain	How to reach --size: contain (pad, never distorts), cover (crop to fill), or stretch (distorts to fill)
--pad-color	String	000000	Pad color for --fit contain, as RRGGBB hex
--loop-count	Int	0	GIF loop count (0 = infinite)
--palette-strategy	String	auto	Color palette strategy: auto, global, or per-frame
--format	String	gif	Output format: gif, webp, apng, or mp4 [Pro]
--audio	String	--	Capture audio into MP4: system, mic, or both. Requires --format mp4. [Pro] Mic prompts for permission once; denial degrades to no audio

Visual Effects

These features require Accessibility permission for event capture. Without it, the flags are accepted but have no effect.

Flag	Type	Default	Description
--cursor-smoothing / --no-cursor-smoothing	Bool	false	Smooth cursor movement between frames
--click-indicators / --no-click-indicators	Bool	false	Show visual indicators on mouse clicks
--type-smoothing / --no-type-smoothing	Bool	false	Normalize typing speed for consistent appearance
--keystroke-badges / --no-keystroke-badges	Bool	false	Show floating badges for keyboard shortcuts
--zoom-cursor / --no-zoom-cursor	Bool	false	Zoom to cursor region for detail focus
--zoom-size	Int	600	Zoom crop width in pixels (height derived from aspect ratio)
--zoom-padding	Int	80	Zoom dead-zone padding in pixels

Timing

Flag	Type	Default	Description
--idle-strategy	String	--	Idle cushioning strategy: cut, ramp, or fade. Disabled by default
--idle-threshold	Double	2.0	Seconds of inactivity before cushioning kicks in

Other

Flag	Description
-q, --quiet	Suppress progress output

Examples

Record Terminal for 10 seconds with click indicators:

quikgif record --app Terminal --duration 10 --click-indicators -o terminal.gif

Record a screen region at 60fps:

quikgif record --region 0,0,1920,1080 --fps 60 --full-resolution -o fullscreen.gif

Record a window sub-region with cursor zoom:

quikgif record --app "VS Code" --crop 0,0,800,400 --zoom-cursor -o editor.gif

Record with polished post-processing:

quikgif record --app Terminal --duration 8 \
  --cursor-smoothing --click-indicators --type-smoothing \
  --keystroke-badges --idle-strategy fade -o polished.gif

Record the iOS Simulator's native device framebuffer, letterboxed to an exact App Store size (--size and --full-resolution are mutually exclusive - --size already lands on exact output dimensions):

quikgif record --simulator-auto --duration 5 --format mp4 \
  --size 1242x2688 --fit contain -o preview.mp4

Record the iOS Simulator at its raw native resolution, no resizing:

quikgif record --simulator-auto --duration 5 --format mp4 --full-resolution -o preview.mp4