Command line

Every command of BetterEdits cli with its options, grouped, with one example each.

Running commands

The command line is the app's own binary. Run it from the workspace folder.

/Applications/BetterEdits.app/Contents/MacOS/BetterEdits cli <command> [value…] [--option value…]

Commands talk to the running app over a Unix socket at ~/Library/Application Support/BetterEdits/cli.sock. If the app is not running the command launches it in the background and waits up to 20 seconds.
Positional values fill a command's required options in order, then its listed positionals: clip-split v1:1 2 is clip-split --clip v1:1 --at 2.
A bare --flag means true. --key=value works too. Numbers and true/false are typed; everything else is text.
Relative paths resolve from the folder you run in.
help lists every command; help <command> or <command> --help prints its options.
A failing command prints why and exits 1. Exit 2 means the app could not be reached.
Every command is an undo step in the app. While the app is locked, commands are refused.

BETTEREDITS_NO_CLI=1 in the app's environment keeps the socket closed.

Refs and times

What	How to write it
Tracks	`v1`, `v2` (video, top first), `a1` (audio), `t1` (text), `s1` (subtitles); a track's name; or its 8-character id
Clips	`v1:2` is the second clip on v1 in time order; or the clip's 8-character id from `timeline`
Subtitle bars	`s1:3` or the bar id
Assets	The file's display name (its filename without extension), its id, or its path
Times	Seconds (`4.5`), `1:02.5`, `end`, `playhead`

Positional refs change after edits; ids do not. Re-read timeline after editing.

Read

Command	Options	Does
`status`		The open project: name, path, duration, playhead, selection, tracks with clip counts
`timeline`	`--track`	Every track with every clip (ref, id, start, end, source in and out, text and position) or every subtitle bar
`media`		The media files the project uses, with `copied: true` for files copied into `media/`
`probe`	`--path` (required)	A file on disk: kind, duration, size, frame rate, sound, HDR
`favorites`		The text favorites and caption styles with font, size and colors
`guide`		The editing guide as text
`help`	`[command]`	The command list, or one command's options

be probe ~/Footage/talk.mov
be timeline --track v1

be stands for the full command above. There is no be on your Mac.

Workspace and projects

Command	Options	Does
`workspace`	`[path]`	Show the workspace, or set one up at a path and switch to it
`media-folders`	`--add`, `--remove`, `--consolidate`, `--force`	List the media folders, add one, or remove one. Removing a folder videos still use needs `--consolidate` (copy the files into the videos first) or `--force`
`projects`		The projects in the workspace, newest first
`project-new`	`[name]`, `--force`	Start a project in its own folder. Without a workspace, an unsaved Untitled project; `--force` discards unsaved changes
`project-open`	`--project` (required), `--force`	Open a project by name, or a `project.json` or `.be` path
`project-save`	`[path]`	Save now; with a path, write a `.be` copy there
`ratio`	`[to]`	Show or change the canvas: `9:16`, `16:9`, `1:1` or `4:5`

be project-new "Hook v2"
be media-folders --remove ~/Footage/June --consolidate

Tracks

Command	Options	Does
`track-add`	`--kind` (required: `video`, `audio`, `text`), `--name`, `--magnetic`, `--top`	Add a track. Video goes right above the audio tracks, or on top with `--top`; audio at the bottom; text on top
`track-set`	`--track` (required), `--name`, `--magnetic`, `--locked`, `--hidden`, `--opacity` (video, 0 to 1), `--muted`, `--solo`, `--volume` (0 to 1.5), `--ducks` (audio)	Change a track
`track-remove`	`--track` (required)	Delete a track and everything on it

be track-set v1 --locked

Clips

Command	Options	Does
`media-import`	`--paths` (required, list)	Register files with the project without placing them
`clip-add`	`--track` (required), `--asset`, `--path`, `--at`, `--in`, `--out`, `--duration`	Put a piece of a file on a video or audio track. Defaults: the whole file (photos 3 s), appended at the end of the track
`placeholder-add`	`--name` (required), `--track`, `--duration` (default 3), `--at`	Add a named stand-in: a black plate on video, silence on audio
`clip-replace`	`--clip` (required), `--asset`, `--path`, `--with`, `--fill`	Swap what is behind a clip or placeholder, keeping its spot and length. `--with` moves another clip in; `--fill` puts a placeholder over the rest when the source is shorter
`clip-slip`	`--clip` (required), `[to]`, `--by`	Slide which part of the file the clip plays. `--to` is the new source in point; `--by` shifts it
`clip-split`	`--clip`, `--at` (both required)	Cut a clip in two at a timeline time
`clip-trim`	`--clip` (required), `--start`, `--end`, `--in`, `--out`	Move a clip's edges. `start` and `end` are timeline times; `in` and `out` are source times
`clip-move`	`--clip`, `--to` (both required), `--track`	Move a clip to a time, optionally onto another track of the same kind
`clip-remove`	`--clip` (required)	Delete a clip
`clip-set`	`--clip` (required), `--volume` (0 to 1.5), `--scale`, `--offsetX`, `--offsetY`, `--cropLeft`, `--cropRight`, `--cropTop`, `--cropBottom` (0 to 0.45), `--name`	Adjust level, picture scale, offset, crop, or a placeholder's name
`clip-duplicate`	`--clip` (required)	Copy a clip, or a subtitle bar, right after itself

be clip-add v1 --path ~/Footage/talk.mov --in 12.4 --out 18.9
be clip-split v1:1 2
be clip-replace v1:2 --with v1:5 --fill

Text

Command	Options	Does
`text-add`	`--text` (required), `--at` (default playhead), `--duration` (default 3), `--track`, `--favorite`, `--font`, `--size` (8 to 240), `--color` (`#RRGGBB`), `--uppercase`, `--x`, `--y` (0 to 1)	Put text on screen for a stretch of time, wearing a favorite with overrides
`text-set`	`--clip` (required), `--text`, `--duration`, `--favorite`, `--font`, `--size`, `--color`, `--uppercase`, `--x`, `--y`	Change a text's words, look or position

be text-add "Stop doing this" --at 0 --duration 2.5 --favorite Strong --y 0.3

Captions

Command	Options	Does
`transcript`	`--track`	The words spoken on a track with start and end times. Cached; adds nothing to the project
`captions-generate`	`--source`, `--replace`	Transcribe a track and add a subtitles track of bars, or refill an existing one with `--replace s1`
`captions`	`--track`, `--words`	The bars of a subtitles track, optionally with word timings
`caption-edit`	`--bar` (required), `--action` (`set`, `merge`, `split`, `remove`), `--text`, `--start`, `--end`	Fix one bar
`captions-style`	`--track`, `--style`, `--position` (`top`, `center`, `bottom`), `--offset` (bottom only, 0.05 to 0.5)	Give a subtitles track a caption style and a position

be caption-edit s1:3 --text "Stop doing this"
be captions-style --style "Bold" --position bottom --offset 0.2

Look

Command	Options	Does
`frame`	`--at` (required), `--width` (default 360, max 1080), `--out`	The picture at a time, with text and captions drawn on, as a PNG
`contact-sheet`	`--out`, `--every`, `--times` (list), `--start`, `--end`, `--columns` (default 4), `--width` (default 240)	One PNG of many frames, each labelled with its time. Default: 12 frames over the piece

Without --out, PNGs go to cache/frames/ in the workspace, named after the command and the time. The command prints the path.

be contact-sheet --every 0.5
be frame 3.2 --out cache/frames/hook.png

Drive the app

Command	Options	Does
`seek`	`--at` (required), `--play`	Move the playhead, optionally start playing
`select`	`--target` (required)	Select a clip or bar, or `none` to clear
`app-show`		Bring the window to the front
`undo`		Undo the last change, yours or the user's
`redo`		Redo the last undone change
`export`	`[path]`, `--preview`, `--height`, `--start`, `--end`	Render an MP4 with text and captions burned in. Default path: `projects/<Name>/exports/<Name>-<date>.mp4`. `--preview` is a quick 540p standard-range file; otherwise the footage's own size, HDR kept

be select v1:2
be export --preview

Templates and cloning

Command	Options	Does
`template`	`--out`	The open project as a template: the first video and audio tracks' clips as named segments, every text with its look
`template-import`	`--file` (required), `[name]`, `--here`	Start a project from a template file, or add it to the open project with `--here`
`reel-clone`	`--url` (required), `[name]`	Fetch a reel with `yt-dlp`, analyse it, draft a template, and start a project from it

be template --out hook.json
be template-import hook.json "Hook v3"
be reel-clone https://www.instagram.com/reel/… "Coffee reel"