The clip you need, in a sentence.

library.db (an SQLite index), originals/ filed by year and month, thumbnails/ and renders/ caches, settings.jsonc and a CLAUDE.md. No account, no cloud.

One library is open at a time. Keep one per client or per year and switch with File > Open or Create Library; File > Open Recent lists the ones you have used.

Paths in the database are relative to the folder. Close the library, move or copy the whole folder to an external SSD, a NAS share or a synced folder, and reopen it.

thumbnails/ and renders/ are caches; deleting them costs time, not data. library.db and originals/ are the library, so those are what you back up.

Almost every setting belongs to the open library and is stored in its settings.jsonc, a JSON file with comments that is safe to edit by hand. Keys the app does not know are kept.

geminiApiKey, geminiModel, aiGatewayApiKey, aiGatewayModel, aiConcurrency (1 to 8, default 4), autoTag, libraryDescription, modelPricing, the audio choices, each shelf's look and importDefaults.

Apple silicon or Intel. On macOS 26 the app takes the Liquid Glass look; earlier systems get the same features in the classic style.

Drag files or folders from Finder onto the window (folders are scanned recursively), paste files copied in Finder, or use File > Import Files, which accepts files and folders.

Set properties on everything in the batch (a Location, a Client, a yes/no) and choose whether to tag it with AI once it lands. The last choice is remembered per library.

Files are fingerprinted before anything is copied. If some are already in the library you are asked once, Finder-style, whether to Skip them, keep them as duplicates, or cancel.

Each video is copied into originals/<year>/<month>/ by capture date. Your source file is untouched, and you can delete it once the import has finished and the count looks right.

Dimensions, duration, capture date, camera make and model, lens, codec, frame rate, HDR, audio channels and tracks are read. The poster comes from the first frame, so hover playback matches the still.

Video only: MP4, MOV, M4V and every codec AVFoundation decodes, including iPhone HEVC, HDR and ProRes, previewed natively with no transcoding. Images and audio files are skipped.

One batch runs at a time. A progress bar at the bottom of the window shows the count and offers Cancel; files that fail are listed when the batch finishes.

Library > Rebuild Metadata re-reads every clip's file and refreshes its technical metadata and poster frame. Names, descriptions, properties and highlights are not touched.

Library (Ready), In Progress (New and Draft), Archive and All Clips, each with a count in the sidebar. Every shelf remembers its own layout, sort and columns; Reset View restores the default.

Sort by Imported, Created, Name, Duration, File size, Dimensions, or Relevance while a search is active. The Show menu picks which properties appear as table columns and card tags; long text can wrap.

Click selects, ⌘-click toggles, ⇧-click extends, arrow keys move the selection with ⇧ to extend, Esc clears. Hovering a card plays the clip, muted and looping.

Space opens a Finder-style Quick Look window that follows the selection; ← and → step through the grid without closing it. Space or Esc closes. Double-click opens the clip in its own window.

One clip: name, status, file facts, description, every property and its highlights. Several: what they share, plus Tag All with AI, Tag Empty with AI, Reset, Share, Export to Folder and Move to Trash.

Select several clips and press ⌘E. The bulk edit sheet spells out every change it will make before you apply it.

⌘N opens another window over the same library, with its own shelf, selection and filters. Menu commands act on the window in front.

Move to Trash removes clips after a confirmation; the originals go to the macOS Trash. Reset wipes a clip's name, description, properties and highlights, takes back any AI request, and keeps the file.

New is imported and untouched. Draft means something changed, by hand or because an AI answer landed. Ready is approved. Archived is set aside, kept, and out of the way.

Select one or more clips and press ⌘R, or use the status control in the inspector or the context menu. Approving a row of drafts is ↓, ⌘R, ↓, ⌘R.

The inspector's status control goes back to Draft or out to Archive. The command-line tool sets statuses too, with clips set --status.

Its only effect is that a New clip becomes a Draft when its answer lands. It never marks a clip Ready or Archived, and it never touches a manual property. Approval is a person's job.

What the AI is doing to a clip (nothing, pending, in progress, failed) is its own thing. It shows in the inspector with Cancel and Retry, in the sidebar's progress dial, and as a filter condition.

In Progress's sidebar count is the number of clips still waiting on you. Ready is the settled state, so it is the one status cards do not show as a tag.

Multi-select and single-select (which hold tags), yes/no (yes, no or not set), a 1 to 5 scale drawn as stars, hearts, flames, bolts, dumbbells, dots or a number, and text (a line or several).

AI properties are filled by the model in place of what was there. Manual ones (Client Approved, Location, anything only a person knows) are written only by people and the command-line tool.

The description is what the model reads to decide when a tag applies: "Vibe: Energetic. Fast movement, loud music, high effort." It can only choose from tags you defined; it cannot invent one.

Bare keywords typed without a property go into Tags, a multi-select bucket for words that have not earned their own property yet. Delete a property and its tags move here instead of disappearing.

Create, rename, re-describe, reorder, or switch a select between single and multi. Add, rename, colour or move tags, and merge several into one with every clip keeping the survivor.

Export Properties writes a properties.jsonc and an INSTRUCTIONS.md for editing by hand or by an agent. Import Properties previews every rename, new tag, merge and deletion before it applies.

Type in the inspector (unknown names are created on the fly), drag clips onto a sidebar tag or a view, bulk edit, set it for a whole batch on import, or clips tag --add "Property:Tag" from the terminal.

Every property lists its tags with how many clips carry each on the current shelf. Click a tag to show those clips; click a scale row for that many and up.

Double-click opens the player over the highlight timeline, with the inspector beside it. Space plays and pauses; click a highlight row and playback stays inside its range.

Press S and moving the pointer along a strip scrubs the video, like Final Cut.

A highlight is a named in-point and out-point that lives in the index. A clip can have as many as you like; the AI marks a few when it tags a clip, to be treated as a first draft.

Add Highlight puts a row at the playhead. Drag its edges to set in and out; edges snap to the playhead, other rows and the clip's ends, and ⌥ drags freely. The name becomes the render's filename.

⌘E turns the whole page into a draft: the properties in the inspector and the rows on the timeline go in one Save (⌘S) or one Cancel (Esc).

Pull the clip's own handles in and Save; after "Trim to this range?" the file is cut to the kept range on keyframes. Highlights inside survive, shifted; highlights outside are dropped.

The scissors ask first, then make two clips, before and after the playhead, each with its name, properties and the highlights that fall inside it. The cut lands on the nearest keyframe.

Matches names, descriptions and highlight names. Fuzzy forgives a typo or two ("coastlne" finds coastline), Includes is literal, and Meaning finds synonyms with a bundled on-device sentence model.

All-of or any-of conditions with nested sub-groups: text in any mode, select any/all/none of, yes/no including not set, scale at least/exactly/at most, Orientation, Created, Imported, Status and AI status.

Each active condition is a chip under the toolbar; click its x to drop it. While text is active the grid sorts by Relevance, and the footer offers looser or stricter matching.

"portrait gym clips from this summer, energetic, newest first" comes back as a real filter: tags, dates, orientation, status, a text search and a sort. Words with no tag become a meaning search.

The filter bar shows exactly what was built; change any condition, add one, or drop it. An ask that says nothing about status searches the Library; "drafts with kettlebells" searches In Progress.

Your sentence and the names and descriptions of your properties, tags and views. No footage, no thumbnails. The default model is DeepSeek V4 Flash through a Vercel AI Gateway key; aiGatewayModel picks another.

Save View stores the filter with grid or table, sort and columns. Change an open view and the bar offers Update or Reset Filters. Recent asks are listed under the field to run again.

Drag clips onto a view and BetterClips offers to tag them so they would match: the view's tags come pre-ticked and a scale minimum carries over. Nothing changes until you confirm.

A short name, a one-line description, values for your AI properties chosen from your tags, and a few named highlights. All of it replaces what was there; manual properties are never touched.

A Gemini key in Settings > General, stored in settings.jsonc next to the footage. Default model Gemini 3.6 Flash. "About this library" is the prompt's opening line; the rest is shown read-only.

Tag with AI after import, on by default once a key exists. Tag All with AI or Tag Empty with AI on a selection, where Tag Empty only touches clips with nothing filled yet. Or ai request from the terminal.

Several calls run at once (aiConcurrency, 1 to 8). Pending and in-progress clips show Cancel, failures show their reason with Retry, and rate limits retry on their own. Editing a queued clip waits for the answer.

A downscaled copy of the clip is uploaded to Google's Gemini Files API with your key, along with the prompt. Nothing is sent for clips you do not tag, and nothing without a key.

Settings > AI Usage lists each tag or ask with its clip, model, input and output tokens, duration and cost, with totals at the top. The log lives in the library folder and travels with it.

Cost is computed at call time in USD per million tokens. The app ships today's list; modelPricing in settings.jsonc overrides it. Uploaded video dominates the bill; an ask costs a fraction of a cent.

Without keys, tagging and asking are simply off. Import, statuses, properties, highlights, search, filters, views, export and the command-line tool all work.

Drag from the grid, table, clip page or inspector onto a Final Cut event or timeline, Finder, or any app that accepts files. A clip drags its original; a highlight drags a trimmed copy named after it.

Video and audio samples are copied, not re-encoded: fast, lossless, any codec your Mac plays. Cuts land on keyframes, so a range can start a fraction before the marked in-point.

A highlight's file is made on its first drag and kept in renders/. It is dropped when the highlight moves, the clip's file changes or the export audio setting flips, and rendered again on the next drag.

Copies every selected clip's original to a destination. For two-mic recordings the panel offers original tracks, both mics merged to mono, left mic only, or right mic only.

AirDrop, Messages, Mail and the rest of the macOS share sheet for the selected clips, from the inspector or the context menu.

⌘C puts the selected files on the clipboard for Finder. ⌘V imports files copied from Finder, or pastes one clip's name, description, properties and highlights onto another, one checkbox per field.

Play > Consolidate to mono sends every channel to both speakers while previewing, on by default, file unchanged. Export > Consolidate to mono writes one AAC mono track; video is copied sample for sample.

Choose the stereo mix, the spatial capture, or an external mic's mono track as the default. Applied on import and across the open library; only the QuickTime header is rewritten, never the media.

/Applications/BetterClips.app/Contents/Helpers/betterclips, nothing to install. Pass --library, set $BETTERCLIPS_LIBRARY, or run from inside a library folder and it finds the library itself.

Add --json to any command for machine-readable output. Ids are UUIDs and any unique prefix works; --help on any command lists its options.

info, clips list filtered by shelf, status, tag, view, search mode, AI state, orientation, dates, filter JSON and sort, clips show and path, highlights, properties, tags, views, settings and ai status.

clips set, tag, value, reset and delete; highlights add, set, delete and export; import and export; properties, tags and views create, set, rename and delete; ai request, cancel and retry-failed; settings set.

Writes go through the same service layer, so statuses, single-select rules and tag re-filing behave identically. After every write an open app reloads at once and picks up clips queued for AI.

Written on creation and refreshed on open: what each file is, the tool's path, how the library thinks, every command, and working rules such as prefer existing tags and never mark clips Ready unless asked.

Below the app's section, "Notes about this library" is never rewritten. Put the house rules there: what the footage is for, who approves clips, how to name highlights, which tags are off limits.

clips reset and clips delete are the only destructive commands, and the guide says so. The tool can queue clips for AI but not run it. Keys stay in settings.jsonc, and settings get masks them.