Organize: Library guide

Edit Library

Edit Library is the window where you manage everything in your library: add, move, sort, search, edit, delete, merge, import, and back up. Open it from the Library menu with Edit Library…. The window itself is titled "Library."

Open the window

1. Click the Library icon in the menu bar.
2. Choose Edit Library….

The window opens at the size and position you last left it. It cannot be smaller than 680 by 320 points.

The window

• Toolbar: Edit… (⌘I), Add (the + menu), Snippets, Get Info, Share, and Delete. Edit, Get Info, and Delete need a selection. Share works for one selected item that has a link or an application. It is off for templates and terminal commands.
• Columns: Name, Shortcut, and Path. Path shows the address, the command, or the application path, with its arguments.
• Sort menu (the arrows at the right of the header). See Sort.
• Reading List section at the top, when it has items. See Reading List.
• Recently Deleted section at the bottom, when it has items. See Recently Deleted.
• Footer: shows the iCloud Drive state when the library is kept in iCloud Drive.
• Subtitle: the number of bookmarks and applications in view.

An empty library shows "Your Library Is Empty" with an Add Bookmark button.

Add items

Choose + in the toolbar, or use File > New:

Every sheet has a Folder menu. Choose Top level or an existing folder.

You can also drag items into the window:

• Drag an application from the Finder to add it.
• Drag a web link from a browser to add it as a bookmark, named after its host. If the link is already in your library, the existing item moves to the top level instead of being added twice.
• Other files and folders dropped on the window are ignored. To add a folder, use the Services item described in Services.

If Name new bookmarks from their pages is on in Settings, a bookmark you add by drag or by Services takes its page's title. See Settings.

Select items

• Click a row to select it. Shift-click and Command-click select several rows, as in other Mac lists.
• Double-click a single row to open it.
• Press Return to rename the selected row. Press Escape or Return to finish.
• Press ⌘I, or choose Edit… from the toolbar or the right-click menu, to open Get Info. With several rows selected, Get Info opens the bulk edit sheet.

Sort

• Click a column heading to sort by it. The first click sorts ascending, the second descending, and the third returns to Your Order. An arrow shows the column in use.
• Choose the sort menu, then Your Order, Name, Path, Most Used, or Recently Opened. Name and Path start ascending.
• Shortcut sorts by the first shortcut of each item. Items with no shortcut sort last.
• Path sorts by the address, or the command, or the application path.
• Most Used and Recently Opened order items by how often and how recently you opened them. Folders keep their places at the top.
• Folders are listed before items in every sorted order.

Sorting changes only what this window shows. Your own order, which the Library menu uses, does not change. The sort is not saved when you quit.

Search

Type in the search field at the top right of the window. The prompt reads "Name, URL, command, or keyword."

• Each word you type must match. For example, jira ops finds an item only if both words appear in its name, URL, command, or keywords.
• A folder whose name matches shows all of its contents.
• Any other folder shows only the items inside it that match.
• Dividers never match.
• Recently Deleted is filtered by the same search.

Reorder and move

• Drag onto a folder to move the selected rows into it.
• Drag onto a row that is not a folder to place the dragged rows directly before it. This works only in Your Order. While a column or the sort menu sorts the list, a drop before a row does nothing.
• Drag onto empty space to move the rows to the top level.
• Move to in the right-click menu lists Top level and every folder. Items that would end up inside themselves are not moved.
• Dragging a selected row moves the whole selection.

A bookmark, an application, or a folder link can be dragged into another app. It drops the link or the application file. Folders, dividers, templates, and terminal commands stay inside the window.

Right-click menu

The menu groups its commands as follows:

1. Open, Open All (folders only), Show in Finder (applications only).
2. Edit…, Rename.
3. Add to Reading List, Mark as Read, Mark as Unread, Remove from Reading List, as they apply.
4. Move to, Share….
5. Delete, alone at the bottom.

In Recently Deleted, the menu offers only Restore and Delete Immediately.

Open All opens each bookmark and application in a folder, one after another. It skips terminal commands, templates, dividers, and applications that are no longer installed. Open All asks first when more than five items would open; see Open anything. See Limits and defaults.

Get Info

Select one item and press ⌘I, or choose Edit…. Get Info has one section for each kind of item. Only the fields that apply to the item are shown.

All items

• Name (required).
• Icon: choose Choose… to pick an SF Symbol or an emoji. The popover has Symbols and Emoji tabs, a search field, recent choices, and Use Default. The default is the site's icon for a bookmark, the application's icon for an application, or a standard icon for a folder, divider, or command.
• Color (not for dividers): Red, Orange, Yellow, Green, Blue, Purple, or Gray. The colored dot appears on the icon in the menu and in this window. Click the selected color again to remove it.

Bookmarks, applications, and terminal commands (items that open something)

• Keywords: extra words that find the item in Quick Open and Spotlight, such as "tix" for an issue tracker.
• Open When You Log In: opens the item a few seconds after you log in. This needs Open at login turned on in Settings.
• Notes: plain text, which can span lines. Quick Open and Spotlight show it under the name.
• Shortcuts: see Keyboard shortcuts.

Bookmarks

• URL (required). Save stays off while it is empty.
• Browser: Default Browser, or one of the browsers installed on this Mac.
• Opens In: New Tab or New Window. This applies to the browser the bookmark opens in.
• Ask for a value when opening: turns the bookmark into a template. See Templates.
• Link status and Last checked: shown only after a link check. Read-only. See Check links.

Applications

• Application: the application's path, read-only.
• Opens In: Bring Forward (the default) or New Instance.
• Arguments: passed when the application opens, such as --profile work. Arguments always start a new instance.
• Terminal Command: optional. When set, the item runs this command in Terminal instead of opening the application.

Terminal commands

• Command (required). The command runs in a new Terminal window. Add only commands you trust.

Folders and dividers

• A folder has Name, Icon, and Color. A divider has Name and Icon.

Save is one undo step named Edit. Save stays off until the required fields are filled.

Templates

A template is a bookmark whose address has a value that you type each time you open it.

A named field is plain text unless you declare it. {project} and {id:Issue number} become fields only when their names are listed in Fields, such as project, id:Issue number. Without that, Library shows the text exactly as typed.

1. In Get Info for a bookmark, turn on Ask for a value when opening. The address gets {} at its end.
2. Put {} where the value goes. For one value, that is enough. Library asks for the value when you open the bookmark.
3. For several values, or a value with its own name, declare each name in Fields, such as query:Search, sort. Then write {query} in the address. Each declared name becomes a field. Library asks for all of them in one sheet.
4. A {name} that is not declared in Fields is plain text. Only a bare {} or a declared name is a field.
5. For a bare {}, the Prompt field sets the label. If you leave it empty, the label is "Value."

The Opens line shows the address with each field in place. Values you type are percent-encoded. A template cannot be added to the Reading List, shared, or link-checked, because its address is not complete until a value is typed.

Bulk edit

Select several rows and choose Edit… (or ⌘I). Bulk edit changes only Icon, Color, and Opens In. The bulk sheet changes only the fields you set. Each field starts at Don't Change.

• Icon: Don't Change, Default, or Custom, then Choose… for a symbol or emoji.
• Color: Don't Change, None, or a color. Shown only when at least one selected item can have a color. Dividers are skipped.
• Opens In: shown when the selection has a bookmark or an application. When the selection mixes the two, the labels read "Existing" and "New." Items with no choice are skipped.

The bulk sheet cannot change names, URLs, keywords, notes, shortcuts, or templates. Use Get Info for one item at a time for those. Save stays off until you change a field. All changes apply as one undo step named Edit Items.

Reading List

Use the Reading List to save bookmarks to read later.

1. Right-click one or more bookmarks.
2. Choose Add to Reading List.

Items in the list appear in a Reading List section at the top, unread first, then read. Each one also stays in its folder in the library. Use the right-click menu to Mark as Read, Mark as Unread, or Remove from Reading List. Removing an item from the Reading List leaves it in your library.

Only bookmarks with a fixed address can be added. Templates, applications, folders, and terminal commands cannot.

Delete and Recently Deleted

Deleting moves items to Recently Deleted, so you can get them back. To delete, use the Delete key, Command-Delete, the toolbar's Delete button, or Delete in the right-click menu. Folders go with their contents. Undo is one step named Delete.

• Restore puts an item back in its folder. If that folder no longer exists, the item goes to the top level. Undo is one step named Restore.
• Delete Immediately removes the item for good. It asks for confirmation first, and it cannot be undone.
• Pressing Delete on an item that is already in Recently Deleted asks the same question.
• Items stay in Recently Deleted for 30 days. Library removes older items the next time it saves the library.

Find Duplicates

Choose File > Find Duplicates… to find bookmarks and applications that open the same thing.

Two bookmarks are duplicates when they have the same address and the same browser. The comparison ignores differences in the case of the scheme and host and a trailing slash, and it treats a missing https:// as https://. The path and query keep their case. Two applications are duplicates when they are the same application with the same arguments.

The sheet groups the duplicates under Same link or Same application.

1. Select the copy to keep in each group. The first item in each group is kept unless you choose another.
2. Choose Merge.

Merging removes the other copies. The kept item:

• keeps its own folder and its own shortcuts;
• takes the keywords of every copy in the group;
• takes each shortcut of the removed copies whose key combination is not already used. A shortcut that clashes is not kept, and the summary lists it.

The summary appears in an alert titled Duplicates Merged. Undo is one step named Merge Duplicates.

Import bookmarks

Choose File > Import Bookmarks… to bring in bookmarks from Safari or Chrome.

1. Choose the bookmarks file in the open panel:
   • Safari: Bookmarks.plist in ~/Library/Safari.
   • Chrome: the Bookmarks file in ~/Library/Application Support/Google/Chrome/Default. Press ⇧⌘G in the panel to type a path.
2. Library adds the bookmarks in one folder, named Imported from Safari or Imported from Chrome. Folders keep their structure. Safari's Favorites Bar and Bookmarks Menu keep those names.

Entries that are not web links are skipped. Safari's Reading List and sync folders are not imported. An alert reports how many bookmarks were imported and how many entries were skipped.

The import is one undo step named Import Bookmarks.

If the file can't be read, isn't a Safari or Chrome bookmarks file, or has no web bookmarks, Library says so and changes nothing.

Check links

Choose File > Check Links to check every bookmark now.

• Each address is checked at most once a day. An address that was checked in the last 24 hours is skipped. Up to four addresses are checked at a time.
• Library first sends a HEAD request, which asks only for the headers. If the server refuses it, Library sends a GET request and reads up to 64 KB of the page to decide.
• A bookmark whose page returned an error (a 4xx or 5xx code) shows a warning icon, with Broken link in its tooltip.
• A bookmark whose site did not answer (no response, a timeout, a redirect loop, or more than five redirects) shows Unreachable link.
• Get Info shows the result and the time of the last check.

To check once a day in the background, turn on Check links periodically in Settings > General. It is off by default. The daily check runs while Library is open.

Link checks are not undo steps.

Export and restore

Export and restore are in two places.

Export

• File > Export Library… or Settings > General > Backup > Export….
• The file is named Library Backup followed by the date, in JSON.
• The backup has your bookmarks, folders, shortcuts, icons, keywords, colors, templates, and Open at Login settings.
• Items in Recently Deleted are not exported.
• Clipboard items are not exported. Pinned clipboard items are encrypted with a key that stays on this Mac.

Restore

• Settings > General > Backup > Restore….
• Library asks you to confirm Replace Library. The default button is Cancel.
• Restoring replaces your current library. Undo restores the library you had before.
• An item in the backup whose id is already used by an item in Recently Deleted gets a new id, so the two do not collide.
• Restore is refused when bookmarks.json cannot be read, because the restored library could not be saved.

Keys in this window

These keys work while the Library window is in front. Apart from ⌘N, ⇧⌘N, and ⌘I, the File menu items have no key.

Where your data is stored and whether it syncs

The library is kept in bookmarks.json, and it syncs when Keep Library in iCloud Drive is on. Where each kind of data is kept is in Storage and sync.

Limits and defaults

• Undo uses the Library window's undo history. Edits made before the window has been opened in this session are not undoable. Changes that come from another Mac or from iCloud clear the undo history.
• Recently Deleted keeps items for 30 days.
• Open All asks before opening more than five items. This threshold is fixed at five. There is no setting for it.
• Open All skips terminal commands, templates, dividers, and applications that are no longer installed. It opens the rest one after another, about 150 milliseconds apart.
• Link check requests each address at most once per 24 hours, with up to four addresses at a time, and gives up on a request after 10 seconds.
• Most Used and Recently Opened use the usage recorded on this Mac.
• The window size and position are remembered.

Settings that change the manager

• Settings > General > Name new bookmarks from their pages: off by default. When it is on, a new bookmark takes its page's title.
• Settings > General > Check links periodically: off by default.
• Settings > General > Keep Library in iCloud Drive: off by default.
• Settings > General > Backup: Export and Restore.
• Settings > General > Open at login must be on for Open When You Log In on an item to do anything.

Caveats

• Terminal commands marked Open When You Log In run in Terminal when Library opens at login. They run without a confirmation unless Confirm Terminal Commands is on. See Keyboard shortcuts for the other places a command runs.
• Bulk edit does not change names, addresses, keywords, notes, or shortcuts.
• Sorting is not saved between launches.
• The Library menu item is Edit Library…, and the window is titled "Library."

Color items

A color is a dot that helps you sort items at a glance. Use colors to organize your library, not to show status. Library has seven colors: red, orange, yellow, green, blue, purple, and gray.

• Set a color. Select an item, press ⌘I to open Get Info, and choose a dot under Color. Choose the same dot again to clear it.
• Set a color on several items. Select them and edit them together. The sheet has a Color menu. Choose None to clear the color on all of them.
• See the color. The dot appears on the item's icon in the menu bar, in Quick Open, and in the Library window.
• Find colored items. Type the color's name in Quick Open, such as blue. Spotlight finds them by color name too.

The color is saved with the item in bookmarks.json. If you keep your library in iCloud Drive, the color syncs to your other Macs with the item.

Add notes

Write a note on any item in Get Info. Quick Open shows the note under the item's name. Spotlight includes it in the description. Notes are plain text and stay in your library.