---
name: smoothcapture-cli
description: Record the screen, take polished screenshots, apply smart zoom effects, and export demo videos by driving SmoothCapture from the command line. Use when asked to produce a demo/screen recording video, take or beautify a screenshot, automate SmoothCapture, or export/edit a .smoothcapture project without the UI.
---

# SmoothCapture CLI

SmoothCapture (https://www.smoothcapture.app) exposes a CLI control channel: `<app binary> cli <command>`. The app binary doubles as the CLI client:

```bash
SC="/Applications/SmoothCapture.app/Contents/MacOS/SmoothCapture"
# or, after `"$SC" cli install-symlink`: smoothcapture cli <command>
```

Results are one JSON line on stdout (`.data` holds the payload); progress/events stream to stderr, or to stdout as JSON with `--json`. Non-zero exit = failure with a JSON error carrying `code`, `message`, `hint`.

## Core workflow

```bash
"$SC" cli ping                                   # reachable? auto-launches the app
"$SC" cli devices --json                         # display/window/camera/mic ids
"$SC" cli record start --display 3               # or --window <id>, --area x,y,w,h
# ... drive the product with real mouse clicks (clicks become zoom anchors) ...
BUNDLE=$("$SC" cli record stop --json | jq -r '.data.bundlePath')
"$SC" cli project autozoom --path "$BUNDLE"      # cinematic zooms from click data
"$SC" cli export --path "$BUNDLE" --output demo.mp4 --preset 1080p30
```

Fine-grained effect edits (background, padding, aspect ratio, webcam layout, manual zooms, trims) are made by editing `project.json` inside the bundle, then exporting. Never edit it while the project is open in the editor (or run `cli project reload` immediately after).

## Screenshots

```bash
"$SC" cli screenshot --output shot.png                 # raw retina capture, cursor hidden
"$SC" cli screenshot --window 5533 --pretty --output hero.png   # background + padding + rounded corners + shadow
"$SC" cli backgrounds --json                           # names for --background
```

`--pretty` (implied by `--background/--padding/--corner-radius`) produces a marketing-ready image styled like SmoothCapture's video exports. Targets and ids work exactly like `record start` (`--display`, `--window`, `--area x,y,w,h`).

## Must-knows

- Server is off by default: `"$SC" cli enable` once (or Settings -> General -> Command-line control). `SERVER_DISABLED` -> exit 3.
- `PERMISSION_SCREEN_RECORDING` (exit 4) can only be fixed by a human in System Settings -> Privacy & Security -> Screen Recording. Report it; don't retry.
- Smart zoom needs real clicks during recording; zero clicks -> zero zoom effects (success with `zoomEffectsGenerated: 0`).
- One recording / one headless project op at a time; a project open in the editor blocks headless ops (`PROJECT_OPEN_IN_EDITOR`).
- Record defaults: no mic, no camera, no system audio, no countdown - pass flags to opt in.

## References

- [references/cli-reference.md](references/cli-reference.md) - every command, flags, JSON schemas, error/exit codes
- [references/project-json-reference.md](references/project-json-reference.md) - bundle layout + project.json field guide for effect edits
- [references/demo-video-workflow.md](references/demo-video-workflow.md) - full recipe with polish tips and failure handling