AddToSidebar

A macOS command-line tool that adds any folder to Finder's sidebar Favorites section. Supports single-user, multi-user deployment, and automatic setup for new users via LaunchAgent.

Features

• Add any folder to Finder sidebar Favorites from the command line
• Idempotent — safely re-run without creating duplicates
• --all-users — deploy to every user account on the system
• --new-users — install a LaunchAgent so future users get the sidebar item at login
• --create-dir — create the target directory if it doesn't exist
• --uninstall — remove the LaunchAgent installed by --new-users

Requirements

• macOS 11+ (Big Sur or later)
• Xcode Command Line Tools (xcode-select --install)

Build

# Native build (current architecture)
make

# Universal binary (arm64 + x86_64)
make universal

Or compile directly:

clang -fobjc-arc -O2 -framework Foundation -framework CoreServices -o AddToSidebar AddToSidebar.m

A prebuilt arm64 binary is included in the repo for convenience.

Install

# Copy to /usr/local/bin
sudo make install

# Or manually
sudo cp AddToSidebar /usr/local/bin/
sudo chmod 755 /usr/local/bin/AddToSidebar

Usage

AddToSidebar [options] <path> [display-name]

Options

Option	Description
--create-dir	Create the target directory if it doesn't exist
--all-users	Add the sidebar item for every existing user (requires sudo)
--new-users	Install a LaunchAgent so future users get the item at login (requires sudo)
--uninstall	Remove the LaunchAgent installed by --new-users (requires sudo)

Examples

Add a folder to your own sidebar:

AddToSidebar ~/Projects

Add with a custom display name:

AddToSidebar ~/my-shared-files "Shared Files"

Create the directory if it doesn't exist:

AddToSidebar --create-dir ~/SharedDocs

Deploy for all users on the system + set up for future users:

sudo AddToSidebar --all-users --new-users --create-dir '~/SharedDocs' "Shared Docs"

This will:

1. Create ~/SharedDocs in each user's home directory (with correct ownership)
2. Add it to the Finder sidebar for every currently logged-in user
3. Install a LaunchAgent at /Library/LaunchAgents/com.addtosidebar.SharedDocs.plist so new users get the item automatically at login

Remove the LaunchAgent:

sudo AddToSidebar --uninstall '~/SharedDocs'

How It Works

AddToSidebar uses the macOS LSSharedFileList API to programmatically add items to the Finder sidebar Favorites list. This is the same API that Finder uses internally.

Single-user mode (no flags or --create-dir only):

• Expands the path, optionally creates the directory, checks for duplicates, and inserts the item

--all-users:

• Enumerates all real user accounts (UID >= 500) via dscl
• For each user, resolves ~ to their home directory
• Runs the sidebar add in the user's context via launchctl asuser

--new-users:

• Installs a LaunchAgent plist in /Library/LaunchAgents/ that runs AddToSidebar at login (RunAtLoad = true, LimitLoadToSessionType = Aqua)
• The plist label is derived from the folder name (e.g., com.addtosidebar.SharedDocs)

Uninstall

Remove the binary:

sudo make uninstall
# or
sudo rm /usr/local/bin/AddToSidebar

Remove any LaunchAgents created with --new-users:

sudo AddToSidebar --uninstall '~/YourFolder'
# or manually
sudo rm /Library/LaunchAgents/com.addtosidebar.*.plist

Notes

• The LSSharedFileList API is deprecated by Apple but remains functional through macOS 15 (Sequoia). There is no replacement API for programmatic sidebar management.
• The --all-users flag only works for users who are currently logged in (Finder needs an active GUI session). Users not logged in will get the sidebar item via the LaunchAgent if --new-users was also used.
• Running without sudo in single-user mode modifies only the current user's sidebar.

License

MIT