# 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 ` (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 ` | `--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 …` | | Everything about the clips, including the file path and highlights. | | `clips path …` | | The original file's absolute path. | | `clips set …` | `--name TEXT`, `--description TEXT`, `--status new\|draft\|ready\|archive` | Names, describes, or sets the status. Blank clears a name or description. | | `clips tag …` | `--add "Prop:Tag"` (repeatable), `--remove "Prop:Tag"` (repeatable), `--create` | Adds and removes tags. `--create` makes tags in `--add` that do not exist. | | `clips value …` | `--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 …` | `--keep-status` | Wipes tags, values, name, description and highlights. New again unless `--keep-status`. Not undoable. | | `clips delete …` | `--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 ` | Every highlight, or one clip's. | | `highlights add ` | `--in SECONDS`, `--out SECONDS`, `--name TEXT` | Marks a range. Out must come after in, within the clip. | | `highlights set ` | `--in SECONDS`, `--out SECONDS`, `--name TEXT` | Moves or renames a highlight. A moved range drops its cached render. | | `highlights delete …` | | Removes highlights. The clips stay. | | `highlights export …` | `--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 …` | `--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 …` | `--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 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 ` | | Removes a property. Its tags move to Tags. | | `properties export ` | | Writes `properties.jsonc` and `INSTRUCTIONS.md` into the folder (replaced if it exists). | | `properties import ` | `--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 ` | | The view's filter as JSON, reusable with `--filter-json`. | | `views create ` | `--filter-json JSON` | Saves a view. | | `views rename ` | `--to NEW` | Renames a view. | | `views delete ` | | 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 …` | Puts clips in line for the app's AI tagging. Replaces what the AI owns on them when the answer lands. | | `ai cancel …` | 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](https://docs.usebetterapps.com/betterlibrary/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."