The command line
Every betterlibrary command, subcommand and flag, with one example each.
The tool
The tool is inside the app bundle:
/Applications/BetterLibrary.app/Contents/Helpers/betterlibrary
The app does not add it to your PATH. The CLAUDE.md in every library carries the full path. A symlink from a folder on your PATH works; the tool resolves symlinks to find its app.
ln -s /Applications/BetterLibrary.app/Contents/Helpers/betterlibrary /usr/local/bin/betterlibrary
Every command takes --library <path> (short: -L). Without it the tool uses $BETTERLIBRARY_LIBRARY, else the library folder enclosing the current directory. Add --json to any command for machine-readable output. Ids are UUIDs; any unique prefix works. --help on any command lists its options; --version prints the app's version.
The tool needs the same live trial or subscription as the app. While the app is locked it prints "BetterLibrary needs an active subscription or trial. Open the app to sign in." and exits with status 2. --help and --version always work.
After every write, an open app reloads. Clips the tool queues for AI join the app's queue.
Library
| Command | Flags | Does |
|---|---|---|
create <path> | --json | Makes a library in the folder (created if missing) and writes its CLAUDE.md. Takes no --library. |
info | Counts by status, AI counts, highlights, views, properties with their tags, the about text, whether the Mac is signed in. | |
guide | --write | Prints the CLAUDE.md guide, or writes and refreshes it in the library. |
betterlibrary create ~/Movies/BetterLibrary/Gym
betterlibrary info --library ~/Movies/BetterLibrary/Gym --json
Clips
clips alone is clips list.
| Command | Flags | Does |
|---|---|---|
clips list | --shelf library|all|in-progress|archive, --status new|draft|ready|archive (repeatable), --tag "Prop:Tag" (repeatable, all of them), --view NAME, --search TEXT, --mode fuzzy|includes|meaning, --ai none|pending|in-progress|failed, --orientation portrait|landscape|square, --after YYYY-MM-DD, --before YYYY-MM-DD, --filter-json JSON, --sort KEY, --asc, --desc, --limit N, --ids | Lists clips. The default shelf is all. --sort takes imported, created, name, duration, size, pixels, relevance, or a property name. --ids prints one id per line. |
clips show <id>… | Everything about the clips, including the file path and highlights. | |
clips path <id>… | The original file's absolute path. | |
clips set <id>… | --name TEXT, --description TEXT, --status new|draft|ready|archive | Names, describes, or sets the status. Blank clears a name or description. |
clips tag <id>… | --add "Prop:Tag" (repeatable), --remove "Prop:Tag" (repeatable), --create | Adds and removes tags. --create makes tags in --add that do not exist. |
clips value <id>… | --property NAME, --value VALUE or --clear | Sets a yes/no, 1 to 5 or text property. yes, no, true, false, 1 to 5, or text. |
clips reset <id>… | --keep-status | Wipes tags, values, name, description and highlights. New again unless --keep-status. Not undoable. |
clips delete <id>… | --permanent | Removes the clips. Originals go to the Trash, or are deleted outright with --permanent. Not undoable. |
--after and --before filter on the created date. --search without --sort sorts by relevance. In meaning mode the tool reads the vectors the app keeps; clips the app has not indexed yet are counted in a note.
betterlibrary clips list --shelf in-progress --tag "Exercise:Squat" --sort duration --limit 20
betterlibrary clips list --search "handstand on the beach" --mode meaning --json
betterlibrary clips set 3f2a --name "Kettlebell swings, side view" --status ready
betterlibrary clips tag 3f2a 9b10 --add "Energy:Intense" --remove "Energy:Calm"
betterlibrary clips value 3f2a --property "Face visible" --value yes
A tag is written Property:Tag. A bare Tag works when the name is unique across properties. A property can also be named as #id.
Highlights
highlights alone is highlights list.
| Command | Flags | Does |
|---|---|---|
highlights list | --clip <id> | Every highlight, or one clip's. |
highlights add <clip> | --in SECONDS, --out SECONDS, --name TEXT | Marks a range. Out must come after in, within the clip. |
highlights set <id> | --in SECONDS, --out SECONDS, --name TEXT | Moves or renames a highlight. A moved range drops its cached render. |
highlights delete <id>… | Removes highlights. The clips stay. | |
highlights export <id>… | --to DIR, --numbered | Cuts the highlights out of their clips into a folder, lossless, on keyframes. --numbered prefixes 01, 02, in the order given. |
betterlibrary highlights add 3f2a --in 12.5 --out 18 --name "Clean rep"
betterlibrary highlights export a1b2 c3d4 --to ~/Desktop/reel --numbered
Import and export
| Command | Flags | Does |
|---|---|---|
import <path>… | --allow-duplicates, --tag "Prop:Tag" (repeatable), --no-ai, --ai | Brings files or folders in. Duplicates are skipped unless allowed. --tag goes onto every new clip. --ai and --no-ai override the library's autoTag. |
export <id>… | --to DIR | Copies the clips' originals into a folder. |
betterlibrary import ~/Footage/2026-09-08 --tag "Client:Acme" --no-ai
betterlibrary export 3f2a 9b10 --to ~/Desktop/selects
Properties
properties alone is properties list.
| Command | Flags | Does |
|---|---|---|
properties list | Every property with its tags and descriptions. | |
properties create | --name NAME, --type multiSelect|singleSelect|boolean|text|scale, --description TEXT, --manual, --ai, --symbol star|heart|flame|bolt|dumbbell|dot|number, --multiline | Adds a property. Scales default to manual; everything else to AI. |
properties set <name or #id> | --name NEW, --description TEXT, --ai, --manual, --type multiSelect|singleSelect, --symbol, --multiline, --single-line | Renames, describes or reconfigures. Only select types can change into each other. |
properties delete <name or #id> | Removes a property. Its tags move to Tags. | |
properties export <folder> | Writes properties.jsonc and INSTRUCTIONS.md into the folder (replaced if it exists). | |
properties import <file> | --dry-run | Applies a properties.jsonc: renames, new tags, merges, deletions, validated first. --dry-run shows the changes without writing. |
betterlibrary properties create --name "Shot type" --type singleSelect --description "How the camera frames the subject"
betterlibrary properties export ~/Desktop/schema
betterlibrary properties import ~/Desktop/schema/properties.jsonc --dry-run
Tags
tags alone is tags list.
| Command | Flags | Does |
|---|---|---|
tags list | --property NAME | Every tag with its description and colour, or one property's. |
tags create | --name NAME, --property NAME, --description TEXT, --color #RRGGBB | Adds a tag. Without --property it goes into Tags. |
tags set "Prop:Tag" | --name NEW, --description TEXT, --color #RRGGBB or none, --property NAME | Renames, describes, recolours or moves a tag. Moving it into a property that has a same-named tag merges the two. |
tags delete "Prop:Tag"… | Removes tags and their assignments. |
betterlibrary tags create --property "Shot type" --name "Close-up" --description "Face or hands fill the frame"
betterlibrary tags set "Tags:beach" --property "Scene"
Views
views alone is views list.
| Command | Flags | Does |
|---|---|---|
views list | Every saved view and how many conditions it has. | |
views show <name> | The view's filter as JSON, reusable with --filter-json. | |
views create <name> | --filter-json JSON | Saves a view. |
views rename <name> | --to NEW | Renames a view. |
views delete <name> | Removes a view. The clips stay. |
betterlibrary views show "Reel candidates" --json
betterlibrary views create "Portrait drafts" --filter-json "$(betterlibrary views show "Reel candidates" --json | jq -c .predicate)"
AI
ai alone is ai status.
| Command | Does |
|---|---|
ai status | Clips pending, in progress and failed, and whether the Mac is signed in. |
ai request <id>… | Puts clips in line for the app's AI tagging. Replaces what the AI owns on them when the answer lands. |
ai cancel <id>… | Takes clips out of the queue. |
ai retry-failed | Queues every clip whose last request failed. |
The app runs the queue while it is open with the library. The tool never calls the model itself.
betterlibrary ai request $(betterlibrary clips list --status new --ids)
Settings
settings alone is settings get.
| Command | Does |
|---|---|
settings get [KEY] | Prints one key, or every key. Keys whose name contains "key" are masked. |
settings set KEY VALUE | Sets a key. true and false become booleans, a whole number becomes a number, anything else text. |
settings unset KEY | Removes a key. |
Known keys: libraryDescription, geminiModel, aiGatewayModel, aiConcurrency, autoTag, playbackMono, exportMono, preferredAudioTrack, skimming. See Settings.
betterlibrary settings set libraryDescription "Client b-roll from the Lisbon shoot, for Reels"
betterlibrary settings set aiConcurrency 2
Exit status and output
Text output is for reading; --json is for programs and is the form to prefer. Errors go to standard error with a non-zero exit status. A validation error names what was missing, for example "Give --name, --description or --status."