Learn · Guide 10 of 10
CLI quick reference
The commands you’ll use most, grouped. Run them in a project folder. htcut help lists every command and option.
Times can be written 2.5s, 75f (frames), 2:05 or a timecode. Clip ids are the 8-character prefixes htcut read prints. Most editing commands take --dry-run.
Project and state
htcut init DIR --name N --width 1080 --height 1920- New project, with its graphics, CLAUDE.md and Claude hooks
htcut add-media FILES…- Add video, audio and images
htcut read- The timeline: rows, clips, ids and sources
htcut ui- What you have in the app: playhead, clips under it, selection
htcut status · htcut log- Current revision and the edit history
htcut undo · htcut redo- Undo or redo the latest edit, whoever made it
htcut op apply ops.json --base-rev N --label L- Apply a list of edits as one undoable step
htcut doctor- What this Mac has for HTCUT and what’s missing, each with the fix
htcut models list · install NAME- The optional add-ons: whisper (transcripts), rvm and sam2 (cut-outs)
Editing
htcut ripple cut --from T --to T- Remove time from every row (also insert, trim)
htcut transition list · add KIND --at T- Transitions on cuts, or on one edge with
--inor--out htcut compound make --clips A,B · break --clip X- Group clips into one, or split them out again
htcut speed --clip ID 0.5 [--smooth on]- Retime, or
--ramp hero(also rampUp, rampDown, bullet) htcut jl --clip ID --l 0.5- J or L cut at the clip’s end
htcut sync --ref ID --clips ID,…- Line clips up by their sound
htcut track list · rename · role- Rows and their roles
Text and graphics
htcut templates- Graphics in this project and their fields
htcut graphic NAME --at 1,2.5 --vars JSON- Stills and a sheet of a graphic, plus the cut-off-text check
htcut captions --words 3- Animated captions from the voice row
htcut brand list · apply NAME- Brand kits across projects
Sound
htcut audio normalize · denoise · enhance- Level and clean up, by
--clip,--trackor--role htcut audio match --clip ID --to REF- Make one mic sound like another
htcut audio duck on- Duck music under speech
htcut alts find · add · use- Music and effect choices to audition in the app
htcut sfx- Sound effects on transitions and graphic entrances
htcut master --gain dB · --limit -1- Gain and true-peak limit on the whole mix
htcut loudness-check FILE- LUFS and true peak of any file
Transcript
htcut transcript- The words, with indexes
htcut transcript cut --text "words"- Cut words out of the timeline
htcut transcript clean --dry-run- Pauses, fillers, doubled words and retakes
htcut stumbles --fix --dry-run- Stumbles left in the cut
htcut fix-speech --dry-run- Extend clips that clip a word
Look
htcut grade --clip ID --lut FILE · grade match- LUTs and colour matching
htcut skin --talking-heads --preset natural- Skin retouch
htcut mask set --clip ID --method person- Cut-outs: subject, person, video, points, chroma, luma
htcut mask behind --clip GRAPHIC- Put a graphic behind the subject
htcut device --clip ID circle- Phone, tablet and laptop frames, circle and rounded PIPs
htcut steady --clip ID 0.7- Stabilise
htcut punch · htcut screenzoom --clip ID- Punch-ins on jump cuts; zooms on screen recordings
Shorts, checks and export
htcut shorts · shorts make N- Find and make Shorts
htcut frame T -o f.png [--overlay safe]- One rendered frame, optionally with Shorts safe zones
htcut sheet -o sheet.png- Contact sheet of the whole timeline
htcut check- Overlaps, gaps, missing media, clipped words
htcut preflight- The pre-publish checklist
htcut jobs --wait- Wait for background renders
htcut export -o out.mp4 [--preset hevc_2160]- Export; prints the loudness check
Publishing
htcut chapters add --at T "Title"- YouTube chapters
htcut description · htcut post- The description and everything to paste
htcut thumbs- Best face frames for thumbnails
htcut version save "Name" · review make- Versions and local review links
htcut import-capcut DRAFT NEWDIR- Bring in a CapCut desktop project
htcut relink --search DIR- Find moved media
Found something wrong, or want a command that isn’t here? Open an issue on GitHub.