kcrawford/dockutil

command line tool for managing dock items

INTRODUCTION

dockutil is a command line utility for managing macOS dock items. It is currently written in Swift.

• Compatible with macOS Big Sur through Sonoma (use 2.x version for older OSes)
• Add, List, Move, Find, Remove Dock Items
• Supports Applications, Folders, Stacks, URLs.
• Can act on a specific dock plist or every dock plist in a folder of home directories

LICENSE

Apache 2

CHANGELOG

Version 3.1.1

• Fix bug where dockutil would mistakenly call sudo to run as user
• Ensure paths to apps in Cryptexes get added as normal apps rather than symlinks

Version 3.1.0

• Convert to Swift Package Manager package

Version 3.0.0

• Rewrite in Swift for macOS 12.3 compatibility
• Feature compatibility with previous version
• Find, Add, Remove by bundle identifier, URL or path
• Allow multiple actions in single run (add, remove can be combined and specified multiple times)

Version 2.0.5

• 10.12 fix for Dock restart
• Add and remove spacer tiles

Version 2.0.4

• Allow removal by app bundle identifier (credit to Yoann Gini)
• Bug fixes for plist quoting (credit to VitosX)

Version 2.0.3

• Wait for dock to be setup by Apple before modifying (useful for first login scripts)

Version 2.0.2

• Bug Fix for 10.9.x

Version 2.0.1

• Yosemite compatibility
• Support for multiple removals

Version 2.0.0

• Remove restart of cfprefsd in favor of using defaults
• Bumped to version 2 because some backend changes may break compatibility with older OS versions
• Please test and report any issues

Version 1.1.4

• Restart cfprefsd before restarting Dock to ensure settings are read

Version 1.1.3

• fix issue with missing labels and removals

Version 1.1.2

• fix issue with replacing a url dock item
• add legacy support --hupdock option for backward compatibility
• fix paths with spaces when passing full path to plist

Version 1.1

• fixes many issues with paths (should now work with Default User Template)
• adds option to not restart the dock (--no-restart)
• fixes issue where item would be added multiple times (use --replacing to update an existing item)
• resolves deprecation warnings
• adds option to remove all items (--remove all)
• fix issue with removals when a url exists in a dock
• adds option --version to output version

USAGE

usage:     dockutil -h
usage:     dockutil --add <path to item> | <url> [--label <label>] [ folder_options ] [ position_options ] [--no-restart] [ plist_location_specification ]
usage:     dockutil --remove <dock item label> | <app bundle id> | all | spacer-tiles [--no-restart] [ plist_location_specification ]
usage:     dockutil --move <dock item label>  position_options [ plist_location_specification ]
usage:     dockutil --find <dock item label> [ plist_location_specification ]
usage:     dockutil --list [ plist_location_specification ]
usage:     dockutil --version

position_options:
  --replacing <dock item label name>                            replaces the item with the given dock label or adds the item to the end if item to replace is not found
  --position [ index_number | beginning | end | middle ]        inserts the item at a fixed position: can be an position by index number or keyword
  --after <dock item label name>                                inserts the item immediately after the given dock label or at the end if the item is not found
  --before <dock item label name>                               inserts the item immediately before the given dock label or at the end if the item is not found
  --section [ apps | others ]                                   specifies whether the item should be added to the apps or others section

plist_location_specifications:
  <path to a specific plist>                                    default is the dock plist for current user
  <path to a home directory>
  --allhomes                                                    attempts to locate all home directories and perform the operation on each of them
  --homeloc                                                     overrides the default /Users location for home directories

folder_options:
  --view [grid|fan|list|auto]                                   stack view option
  --display [folder|stack]                                      how to display a folder's icon
  --sort [name|dateadded|datemodified|datecreated|kind]         sets sorting option for a folder view

Examples:
  The following adds TextEdit.app to the end of the current user's dock:
           dockutil --add /Applications/TextEdit.app

  The following replaces Time Machine with TextEdit.app in the current user's dock:
           dockutil --add /Applications/TextEdit.app --replacing 'Time Machine'

  The following adds TextEdit.app after the item Time Machine in every user's dock on that machine:
           dockutil --add /Applications/TextEdit.app --after 'Time Machine' --allhomes

  The following adds ~/Downloads as a grid stack displayed as a folder for every user's dock on that machine:
           dockutil --add '~/Downloads' --view grid --display folder --allhomes

  The following adds a url dock item after the Downloads dock item for every user's dock on that machine:
           dockutil --add vnc://miniserver.local --label 'Mini VNC' --after Downloads --allhomes

  The following removes System Preferences from every user's dock on that machine:
           dockutil --remove 'System Preferences' --allhomes

  The following moves System Preferences to the second slot on every user's dock on that machine:
           dockutil --move 'System Preferences' --position 2 --allhomes

  The following finds any instance of iTunes in the specified home directory's dock:
           dockutil --find iTunes /Users/jsmith

  The following lists all dock items for all home directories at homeloc in the form: item<tab>path<tab><section>tab<plist>
           dockutil --list --homeloc /Volumes/RAID/Homes --allhomes

  The following adds Firefox after Safari in the Default User Template without restarting the Dock
           dockutil --add /Applications/Firefox.app --after Safari --no-restart '/System/Library/User Template/English.lproj'

  The following adds a spacer tile in the apps section after Mail
           dockutil --add '' --type spacer --section apps --after Mail

  The following removes all spacer tiles
           dockutil --remove spacer-tiles

Notes:
  When specifying a relative path like ~/Documents with the --allhomes option, ~/Documents must be quoted like '~/Documents' to get the item relative to each home
  When specifying paths in macOS 11 Big Sur or higher note that the path to applications is /System/Applications so to add TextEdit.app :
          dockutil --add /System/Applications/TextEdit.app

LIMITATIONS AND DEPENDENCIES

dockutil's Issues

El Cap compatible?

We have a variety of users from 10.9 through 10.11...has this been tested/used on El Cap machines?

Thanks!

Error - Traceback KeyError: 'persistent-others'

dockutil errors when trying to make changes to a plist with no 'persistent-others'. Should dockutil care that there isn't a persistent-others when writing to persistent-apps or listing contents?

Eg.
sh-3.2# /Library/Future/Scripts/dockutil --list '/System/Library/User Template/English.lproj'
Traceback (most recent call last):
File "/Library/Future/Scripts/dockutil", line 663, in
main()
File "/Library/Future/Scripts/dockutil", line 279, in main
for item in pl[section]:
KeyError: 'persistent-others'

sh-3.2# /Library/Future/Scripts/dockutil --add /Applications/Firefox.app --no-restart '/System/Library/User Template/English.lproj'
Traceback (most recent call last):
File "/Library/Future/Scripts/dockutil", line 663, in
main()
File "/Library/Future/Scripts/dockutil", line 365, in main
commitPlist(pl, plist_path, restart_dock)
File "/Library/Future/Scripts/dockutil", line 618, in commitPlist
pl = removeLongs(pl)
File "/Library/Future/Scripts/dockutil", line 649, in removeLongs
for item in pl['persistent-others']:
KeyError: 'persistent-others'

Placing Adobe Illustrator CC 2015.3.app or Adobe After Effects CC 2015.app Icons.

I am having problems with dockutil placing icons for Adobe Illustrator CC 2015.3.app and Adobe After Effects CC 2015.app. The result is a question mark in the dock.

I tested with both versions 2.02 and 2.05. Macs are running El Capitan and Yosemite.

I thought it may be the odd paths that Adobe is using, but other Creative Cloud apps with similar paths do work.

Here are examples of apps & commands that dockutil does successfully work with:
dockutil --add '/Applications/Adobe Photoshop CC 2015.5/Adobe Photoshop CC 2015.5.app'
dockutil --add '/Applications/Adobe Premiere Pro CC 2015.3/Adobe Premiere Pro CC 2015.app'
dockutil --add '/Applications/Adobe Audition CC 2015.2/Adobe Audition CC 2015.app'

However, these two will not work:
dockutil --add '/Applications/Adobe After Effects CC 2015.3/Adobe After Effects CC 2015.app'
dockutil --add '/Applications/Adobe Illustrator CC 2015.3/Adobe Illustrator CC 2015.3.app'

Verbose mode feedback:
snoopy:~ conferenceroom$ /Library/Application\ Support/JAMF/bin/dockutil --add '/Applications/Adobe Illustrator CC 2015.3/Adobe Illustrator CC 2015.3.app'
snoopy:~ conferenceroom$ /Library/Application\ Support/JAMF/bin/dockutil --add '/Applications/Adobe Illustrator CC 2015.3/Adobe Illustrator CC 2015.3.app' -v
verbose: ('processing', '/Users/conferenceroom/Library/Preferences/com.apple.dock.plist')
verbose: ('adding', '/Applications/Adobe Illustrator CC 2015.3/Adobe Illustrator CC 2015.3.app')
verbose: ('adding', {'tile-data': {'file-label': u'Adobe Illustrator CC 2015.3', 'file-data': {'_CFURLStringType': 0, '_CFURLString': u'/Applications/Adobe Illustrator CC 2015.3/Adobe Illustrator CC 2015.3.app'}, 'file-type': 32}, 'tile-type': 'file-tile', 'GUID': '227F2437-3CAB-48FE-83FD-0DC69006C652'})
verbose: ('item added at end',)

Items are added but not always removed

Sometimes when a user logs in, dockutil will add the programs that are called for, but it won't remove all the default dock items. There appears to be no discernible consistency, as I logged in as one user, and it worked famously but logged out and logged in as another user and it gave me everything. The script I have running calls --remove all at the onset, so it should be removing all items. And, it in fact, does work sometimes.

Running in OS X 10.9.4, dockutil 2.0.0.

Any thoughts?

Can't get dockutil to run inside a pkg as the post install script

My problem is simple. I want to set the user dock on a lab of iMacs. I already have dockutil 2.0 installed on all the machines. So I'm thinking a simple two step process, first ...write a script for dockutil to customize the dock, and second ... build a payload free package to deploy and run the script.

This is my test script.

!/bin/bash

Set Dock Applications

/usr/local/bin/dockutil --remove all --allhomes --no-restart
/usr/local/bin/dockutil --add "/Applications/Launchpad.app" --allhomes --no-restart
/usr/local/bin/dockutil --add "/Applications/Safari.app" --allhomes --no-restart
/usr/local/bin/dockutil --add "/Applications/Firefox.app" --allhomes --no-restart
/usr/local/bin/dockutil --add "/Applications/Google Chrome.app" --allhomes

exit 0

When I run the script manually everything looks great. So on too step two.

I'm using Packages to build a payload free pkg, that runs my script as the postinstall script. The package gets built without any errors and when I run the pkg, the installer finishes with a "Installation was completed successfully", but my dock doesn't change.

Thinking maybe it was something with Packages. I also built a payload free pkg with pkgbuild, following Der Flounder's instructions:

http://derflounder.wordpress.com/2012/08/15/creating-payload-free-packages-with-pkgbuild/

example syntax:
sudo pkgbuild --identifier com.company.pkg --nopayload --scripts /pathtoscriptsfolder /pathtodestination.pkg

But I get the same result. The pkg runs with a successful installation, but nothing changes. So I threw in a couple commands to create a folder on the desktop at the start of the script, run the dockutil commands, and then delete the folder. Just so I had a visual clue that the post install script was running.

When I install the pkg, the folder gets created, then deleted, and the dock never changes. I'm stumped since there are no errors messages in the log files because the pkg installed successfully.

At first I thought it was an issue with how I was building my pkg, or maybe the permissions on the shell file, but I've built payload free packages before that work. Is there anything with dockutil that would prevent it from running correctly in a post install script?

Feature request - add --remove_missing

Add a --remove_missing (or similar) option. This would remove dock items which are 'missing' their target applications and are therefore showing a '?' instead of the application icon.

Is this even possible?

Not working on OS X Yosemite

For each command I get

Traceback (most recent call last):
  File "/Users/MoOx/dotfiles/submodules/dockutil/scripts/dockutil", line 647, in <module>
    main()
  File "/Users/MoOx/dotfiles/submodules/dockutil/scripts/dockutil", line 261, in main
    pl = readPlist(plist_path)
  File "/Users/MoOx/dotfiles/submodules/dockutil/scripts/dockutil", line 403, in readPlist
    osx_version = getOsxVersion()
  File "/Users/MoOx/dotfiles/submodules/dockutil/scripts/dockutil", line 391, in getOsxVersion
    raise e
AssertionError

I don't know python so not sure what the issue can be. Maybe I'm missing a requirement ?

dockutil won't run via launchd on 10.9

Hey Kyle -

Thanks for dockutil! It's been a significant improvement over Local MCX, and for that I'm grateful.

I'm pushing dockutil 1.1.4 to all of our lab Macs, and a separate script that runs via a LaunchAgent at login to configure the dock. The script works great with dockutil 1.1.4, but errors out with dockutil 2.0. Here's the script:

#!/bin/bash

SPSS="/Applications/IBM/SPSS/Statistics/21/SPSSStatistics.app"
MAPLE="/Applications/Maple 17/Maple 17.app"

/usr/local/bin/dockutil --remove all --no-restart
/usr/local/bin/dockutil --add "/Applications/Mail.app" --no-restart --position 1
/usr/local/bin/dockutil --add "/Applications/Safari.app" --no-restart --position 2
/usr/local/bin/dockutil --add "/Applications/Firefox.app" --no-restart --position 3
/usr/local/bin/dockutil --add "/Applications/iTunes.app" --no-restart --position 4
/usr/local/bin/dockutil --add "/Applications/System Preferences.app" --no-restart --position 5
/usr/local/bin/dockutil --add "/Applications/Calendar.app" --no-restart --position 6
/usr/local/bin/dockutil --add "/Applications/Contacts.app" --no-restart --position 7
/usr/local/bin/dockutil --add "/Applications/Microsoft Office 2011/Microsoft Excel.app" --no-restart --position 8
/usr/local/bin/dockutil --add "/Applications/Microsoft Office 2011/Microsoft PowerPoint.app" --no-restart --position 9
/usr/local/bin/dockutil --add "/Applications/Microsoft Office 2011/Microsoft Word.app" --no-restart --position 10

if [ -e "$SPSS" ];
then
   /usr/local/bin/dockutil --add "$SPSS" --no-restart --position 11
fi

if [ -e "$MAPLE" ];
then
   /usr/local/bin/dockutil --add "$MAPLE" --no-restart --position 12
fi

/usr/local/bin/dockutil --add "/Applications/GarageBand.app" --no-restart --position 13
/usr/local/bin/dockutil --add "/Applications/iMovie.app" --no-restart --position 14
/usr/local/bin/dockutil --add "/Applications/iPhoto.app" --no-restart --position 15
/usr/local/bin/dockutil --add "/Applications/Adobe Acrobat XI Pro/Adobe Acrobat Pro.app" --position 16

exit 0

Here are the errors I'm seeing. Note that I'm only testing on 10.9.3, not older versions of the OS. I don't know if 10.4-10.8 have the same issues.

Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None
Traceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 340, in main
    if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name):
  File "/usr/local/bin/dockutil", line 485, in addItem
    add_path = unicode(add_path, sys.stdin.encoding)
TypeError: unicode() argument 2 must be string, not None

Any idea what's wrong? If I run my script manually, it works, but not via launchd when logging in (either through a custom LaunchAgent, or via chilcote/outset).

Thanks!

Mike

Dockutil not working on all commands

I am working on an Office 2016 installer that also removed Office 2011 apps and using this to remove the dock icons. I am trying to use it as such:
$dockutil --add '/Applications/Microsoft Excel.app' --replacing 'Microsoft Excel' --allhomes --no-restart
$dockutil --add '/Applications/Microsoft Outlook.app' --replacing 'Microsoft Outlook' --allhomes --no-restart
$dockutil --add '/Applications/Microsoft PowerPoint.app' --replacing 'Microsoft PowerPoint' --allhomes --no-restart
$dockutil --add '/Applications/Microsoft Word.app' --replacing 'Microsoft Word' --allhomes

It will work on one of the items but not all. It will also not remove any of the old dock icons and just seems to process on one, random most of the time, then continue on with the scripts like everything is fine. Should I add anything else to the script or what?

[FR] Add ability to add / remove / move spacers

It would be great to add / remove / move spacer tiles.

http://css-tricks.com/snippets/html/add-spaces-to-dock-in-os-x/

Not working in Snow Leopard

I reverted to 1.1.2 and it is working, but 2.0.0 appears to have a syntax error in the defaults command it sends. When I run it it returns the syntax guide you get if you just type "defaults" at a command prompt with no arguments.

Can't add item to Dock

Hello, I recently tried version 1.2 and now 2.0 with the same results on 10.9.3

Using the command;
dockutil --add /Applications/Self\ Service.app
It refreshes my dock but nothing appears.

dockutil --list
Provides information that Self Service exists in the plist but does not visually appear on the dock.
Self Service /Applications/Self Service.app persistent-apps /Users/test/Library/Preferences/com.apple.dock.plist

I've restarted, logged out and cleared the .db existing in ~/Library/Application Support/Dock/

Any ideas would be greatly appreciated.

Thanks.

Dock stores and reapplies dock-state after restart (Mountain lion)

I couldn't get dockutil working, it seems Mountain Lion's Dock stores it's previous state and then reapplies it to the dock.plist.

A solution to get it working is to delete the file in ~/Library/Application\ Support/Dock/ before restarting. Maybe add this to the tool?

Stand Users and Virtual Machines

I just stumbled into an odd bug that you may not have high motivation to fix, but here it is anyway. :-)

I can't get dockutil to work with Standard Users and virtual machines (I use Parallels). Commands that work again and again with admin users fail with standard users.

I get the feedback:

Script result: afp://Server_Name/Archives already exists in dock. Use --replacing 'afp://Server_Name/Archives' to update an existing item
item afp://Server_Name/Archives was not added to Dock

dockutil works with standard users on real hardware. It works with admin users on both virtual machines and real hardware, but it doesn't work with standard users in Parallels virtual machines, which is how I do much of my testing.

double entries in my Sierra dock

Please refer to this screenshot below.

The 2 icons on the left (MP4 and red icon) was created using dockutil --add /Applications/my-app.app. When I click on the icon on the MP4 icon, another icon showed up (the one of the right). But when I clicked on the red icon, it didn't create a new one like the MP4. is this a problem with Sierra or the script?

Thank you so much.

Mailto: links

Kevin, are mailto: links supported? I'm having trouble adding them- the data written to the plist ends up as /Users/username/mailto:email.address.

no dock restart on 10.12.3

hi there,

version 2.0.5 does not restart the Dock for me on 10.12.3. I am using this command for example:
/usr/local/bin/dockutil --add afp://server.fqdn.tld/scans --label scans --replacing scans

further usage clarification for --remove when targeting specific user as root

I have a launchdaemon running dockutil within a bash array (hey, have to start somewhere). It wants to empty out the dock of a specific user before setting the ones I do want in order, which requires single-quoting 'all' when appending the path to the users folder whose dock I'm altering. Seems like a quick enough comment to add.

Maybe now would also be a good time to request a feature like the list functionality being reversed, so you could do a backup and restore? Should I hack the both of these together as a pull request to review? Thanks, Allister

dock spacers

This is definitely a feature request and not an issue. Is it possible to incorporate spaces into dockutil?

Example: "defaults write com.apple.dock persistent-apps -array-add '{tile-data={}; tile-type="spacer-tile";}'" <---- adds a transparent moveable icon to create spaces in dock.

Can't add Office 2016 item and keep Office 2011 items

My users Dock already contains aliases to Office 2011 applications (installed in /Applications/Microsoft Office 2011/). I would like to add aliases from Office 2016 (like /Applications/Microsoft Excel.app) and I can't make it work
Using

/usr/local/bin/dockutil --add /Applications/Microsoft\ Excel.app --after 'Microsoft Excel'

returns

Microsoft Excel already exists in dock. Use --replacing 'Microsoft Excel' to update an existing item

since both items may share the same name in their Info.plist files.

Replacing the old version by the new one, but I would like to show both versions in the user's Dock.
Would there be a way to check the path of a Dock item in addition to its label ?

dockutil 2.0.0 not working on 10.8

dockutil 2.0.0 works like a champ in my testing on a 10.9 test machine, but on 10.8 machine, regardless of command (--add, --remove, --list) receive "defaults" help text (as though defaults was called with incorrect syntax):

$ /usr/local/bin/dockutil -v --remove TextEdit
verbose: ('processing', '/Users/mpullen/Library/Preferences/com.apple.dock.plist')
Command line interface to a user's defaults.
Syntax:

'defaults' [-currentHost | -host <hostname>] followed by one of the following:
....

then hangs. Ctrl-C produces the following traceback:

^CTraceback (most recent call last):
  File "/usr/local/bin/dockutil", line 627, in <module>
    main()
  File "/usr/local/bin/dockutil", line 260, in main
    pl = readPlist(plist_path)
  File "/usr/local/bin/dockutil", line 395, in readPlist
    plist_string = subprocess.Popen(['plutil', '-convert', 'xml1', export_fifo, '-o', '-'], stdout=subprocess.PIPE).stdout.read()
KeyboardInterrupt

Noticed that Python on the 10.8 machine is Python 2.7.2, but on the 10.9 machine is Python 2.7.5...

Mike

Unable to add chrome correctly

Maybe I'm doing something wrong but the following simple command:

dockutil --add file:///opt/homebrew-cask/Caskroom/google-chrome/latest/Google%20Chrome.app/ --after Launchpad

instead of adding chrome as the third element in the dock, add's a weird globe icon as the second to last icon like this:

Question: dockutil help --no-restart issue?

OS X 10.10.3, dockutil 2.0.2
When working on a script for configuring account docks with outset, I noticed that the --no-restart option is always specified after the users home dir location. I am able to do that on occasion, but mainly it errors out --no-restart does not seem to be a home directory or a dock plist
After moving it ahead of the plist location it seemed to fix it. Is this a bug, or is the help just a little different from actual use? The example given for the User Template has this correct, but the usage at the top doesn't.

In OS X 10.10.2, I have to restart the Dock to see changes

For example, I did

dockutil --add /Applications/TextEdit.app

and the dock was automatically restarted, but TextEdit did not appear. I did killall Dock in the Terminal, and when the Dock restarted, TextEdit was there.

If I had to guess, I'd say that this probably has something to do with preferences caching, but I'm not sure.

dockutil v. 2.0.2

Not able to set relative path to User Template

It is not possible to place an item with an relative path in the user template.

e.g.:

/usr/local/bin/dockutil --add '~/' --view grid --display folder '/System/Library/User Template/Non_localized'

osx Mavericks

Doesn't work on Mavericks anymore.

Claims default dock is not a valid dock plist

I'm getting these errors:

/System/Library/User Template/English.lproj/Library/Preferences/com.apple.dock.plist does not seem to be a home directory or a dock plist

Well, it certainly seems to be a dock plist. Why is dockutil refusing to work with the template dock plist? I'm using the same syntax as the -h help page. This is in 10.10.3 and dockutil 2.0.2.

The only workaround I can think of is for it to alter the current user's dock and then copy that .plist to the template, changing the owner, group, and permissions. But I'd prefer not resort to such a kludge.

Thanks for any thoughts!

Homebrew installation fails

Not sure if this is the right place to report, but do you know who maintains the brew formula? On my machine it fails with:

==> Downloading https://github.com/kcrawford/dockutil/archive/2.0.2.tar.gz
Already downloaded: /Library/Caches/Homebrew/dockutil-2.0.2.tar.gz
==> Downloading https://pypi.python.org/packages/source/p/plist/plist-0.2.tar.gz

curl: (22) The requested URL returned error: 404 Not Found
Error: Failed to download resource "dockutil--plistlib"
Download failed: https://pypi.python.org/packages/source/p/plist/plist-0.2.tar.gz

Dock entries without a "file-label" property can't be removed (eg. default dock.plist from Dock.app bundle)

Since dockutil relies on the "file-label" property to remove Dock items, it is unable to remove Dock items that only contain a "_CFURLString" property, which includes all the dock items in /System/Library/CoreServices/Dock.app/Contents/Resources/English.lproj/default.plist which is useful to copy into User Template on 10.8 to get a default Dock in there to modify.

Issues in 10.12 Sierra

Hi,
dockutil fails to remove dock icons in OSX 10.12 Sierra.

automatic is an unsupported --view argument

dockutil --add ~/Documents --view automatic results in an error

Error processing options: unsupported --view argument

But the help page indicates automatic is a valid argument for --view

folder_options:
  --view [grid|fan|list|automatic]                              stack view option
  --display [folder|stack]                                      how to display a folder's icon
  --sort [name|dateadded|datemodified|datecreated|kind]         sets sorting option for a folder view

2.0.3 does not work with User Templates

Version 2.0.3 crashes when I try to modify dock in User Template folder.
Version 2.0.2 works properly.
I guess os.stat does not like quoted paths.

Traceback (most recent call last):
File "/usr/local/bin/dockutil", line 678, in
main()
File "/usr/local/bin/dockutil", line 269, in main
if os.stat(plist_path).st_uid == os.stat('/dev/console').st_uid:
OSError: [Errno 2] No such file or directory: "'/System/Library/User Template/Non_localized/Library/Preferences/com.apple.dock.plist'"

Feature Request --deleteall

I think it would be good for some cases if there was a handle for a delete all flag. It would come in handy when you need to enforce a specific dock layout ( my scenario is Online Testing, where we need to have safari and the browser on the dock ). It would help so that we could clear the dock and start from scratch that way we know exactly what the dock is. I realize we can do this with profiles, but sometimes those are not the best case.

Feature Request - Check for Duplicate

Would like to see a check for duplicate added if possible.

Finder toolbar

I was wondering if the Finder toolbar is equally malleable? See this question on SO: http://apple.stackexchange.com/questions/197990/add-item-to-finder-toolbar-with-terminal

Not finding plist

Ok, so i have been messing around with dockutil for the passed few days. For the most part easy to use and works great.

So I am trying to modify the Default User Template dock plist. In the dockutil --help it says to use the '/System/Library/User Template/English.lproj' plist. But when i go there, i do not have that plist. So I grab the default plist found in /System/Library/CoreServices/Dock.app/Contents/Resources/en.lproj/.

And change it to com.apple.dock.plist, then push it out to the /System/Library/User Template/English.lproj folder.

Run the dockutil script and get this back

Script result: item Mail was not found in '/System/Library/User Template/English.lproj/Library/Preferences/com.apple.dock.plist' item Contacts was not found in '/System/Library/User Template/English.lproj/Library/Preferences/com.apple.dock.plist' item Maps was not found in '/System/Library/User Template/English.lproj/Library/Preferences/com.apple.dock.plist' item Messages was not found in '/System/Library/User Template/English.lproj/Library/Preferences/com.apple.dock.plist' item FaceTime was not found in '/System/Library/User Template/English.lproj/Library/Preferences/com.apple.dock.plist' item Photo Booth was not found in '/System/Library/User Template/English.lproj/Library/Preferences/com.apple.dock.plist' item iTunes was not found in '/System/Library/User Template/English.lproj/Library/Preferences/com.apple.dock.plist' item iBooks was not found in '/System/Library/User Template/English.lproj/Library/Preferences/com.apple.dock.plist' Microsoft Outlook already exists in dock. Use --replacing 'Microsoft Outlook' to update an existing item item /Applications/Microsoft Office 2011/Microsoft Outlook.app was not added to Dock Microsoft Word already exists in dock. Use --replacing 'Microsoft Word' to update an existing item item /Applications/Microsoft Office 2011/Microsoft Word.app was not added to Dock Microsoft Excel already exists in dock. Use --replacing 'Microsoft Excel' to update an existing item item /Applications/Microsoft Office 2011/Microsoft Excel.app was not added to Dock Traceback (most recent call last): File "/usr/sbin/dockutil", line 663, in main() File "/usr/sbin/dockutil", line 364, in main if addItem(pl, real_add_path, replace_label, position, before_item, after_item, section, displayas, showas, arrangement, tile_type, label_name): File "/usr/sbin/dockutil", line 516, in addItem if tile_replace_candidate[label_key_for_tile(tile_replace_candidate)] == replace_label: KeyError: None

I am running this in Postimage. My goal is to have the dock modify for new users.

Unicode problem, can't remove item with an accent

Hello, I have a problem to remove an item in the dock that the name is 'Mise à jour de logiciels'. This is the french translation for the software Munki.

This is the command that I do and the result:

bash-3.2$ dockutil --remove 'Mise à jour de logiciels' --allhomes
/usr/local/bin/dockutil:605: UnicodeWarning: Unicode equal comparison failed to convert both arguments to Unicode - interpreting them as being unequal
if dock_item['tile-data'].get('file-label') == item_name:
/usr/local/bin/dockutil:616: UnicodeWarning: Unicode equal comparison failed to convert both arguments to Unicode - interpreting them as being unequal
if dock_item['tile-data'].get('file-label') == item_name:
item Mise à jour de logiciels was not found in /Users/pilier/Library/Preferences/com.apple.dock.plist

I tried the command with the version 1.4 and 2.0 of dockutil. If I do the command dockutil --list, the item is showed like this:

Mise à jour de logiciels /Applications/Utilities/Managed Software Update.app/ persistent-apps /Users/pilier/Library/Preferences/com.apple.dock.plist

How can I remove it? Thanks

Blank tile

Something like this:

defaults write com.apple.dock persistent-apps -array-add '{"tile-type"="spacer-tile";}'

Adds a spacer to the dock. Perhaps dockutil can support this.

Add "User Templates" option

Hi there,

I'd like to see an option to create com.apple.dock.plist files in the user templates folder.

That way we could run 1 line that would update all current users docks & all templates docks, so new users get the changes.

Current workaround is to deploy a blank dock & then run each command twice:

The home templates are updated, but not all homes.. so presumably i need to run two lines of script everytime i wish to add an item:

1. For User Templates:
   sudo /usr/bin/dockutil --add '/path to some app' --homeloc '/System/Library/User Template/'
2. For All Existing Users:
   sudo /usr/bin/dockutil --add '/path to some app' --allhomes

Also, as (in @ least 10.8) the templates folders are empty.. create a blank plist OR copy the template from: /System/Library/CoreServices/Dock.app/Contents/Resources/.lproj/default.plist.

Thanks.

Item added to dock via dockutil not able to be removed via dockutil on Sierra

If I dockutil --add /Applications/Appcleaner.app, I am able to see the AppCleaner application in my dock after a logout/login (or reload of the Dock system launchd plist).

If I dockutil --remove /Applications/Appcleaner.app when Appcleaner is present in my dock, I am unable to remove it and get the following error:

$ ./dockutil --remove /Applications/AppCleaner.app
item /Applications/AppCleaner.app was not found in /Users/loyaltyarm/Library/Preferences/com.apple.dock.plist

However, upon inspecting the dock plist with dockutil --list I am able to see that it is in fact present in the plist:

$ ./dockutil --list
Launchpad	file:///Applications/Launchpad.app/	persistent-apps	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
Safari	file:///Applications/Safari.app/	persistent-apps	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
Google Chrome	file:///Applications/Google%20Chrome.app/	persistent-apps	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
iTerm	file:///Applications/iTerm.app/	persistent-apps	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
Xcode	file:///Applications/Xcode.app/	persistent-apps	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
Antetype	file:///Applications/Antetype.app/	persistent-apps	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
System Preferences	file:///Applications/System%20Preferences.app/	persistent-apps	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
Dash	file:///Applications/Dash.app/	persistent-apps	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
App Store	file:///Applications/App%20Store.app/	persistent-apps	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
Notes	file:///Applications/Notes.app/	persistent-apps	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
Beamer	file:///Applications/Beamer.app/	persistent-apps	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
AppCleaner	file:///Applications/AppCleaner.app/	persistent-apps	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
Applications	file:///Applications/	persistent-others	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
Utilities	file:///Applications/Utilities/	persistent-others	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist
Downloads	file:///Users/loyaltyarm/Downloads/	persistent-others	/Users/loyaltyarm/Library/Preferences/com.apple.dock.plist

$ sw_vers
ProductName:	Mac OS X
ProductVersion:	10.12.1
BuildVersion:	16B2657

Remove Using file-data as well as file-label

Consider when file-label is the same for two dock items that have different paths.
I only want to remove one of the dock items and leave the other if it exists.

Is this possible?

Please tag releases

We've had a request to package this in Homebrew. I see the changelog references version numbers; could you tag releases so we have a stable tarball to pull from? Thanks!

does not work when called from a launchagent

I feel like I used dockutil in agents in the 10.9 days. Went to use from an agent with 2.0.2 and 10.11 and could not get it to work. Upgraded to 2.0.3 still not working. Tried umpteen variations of how to identify the currently logged in user in the script, never could get it to work. During troubleshooting i figured out i could get the dockutil statement to work in a LaunchAgent if i assigned the statement to a variable

this does not work
/usr/local/bin/dockutil --add /Users/$USER/Downloads --display folder --section others

for reasons i don't understand this does work

doit=/usr/local/bin/dockutil --add /Users/$USER/Downloads --display folder --section others

What is happening when right click? As it udates dock icon

When i change my dock icon. If just simply right click and check "keep in dock" or if i say "show in finder" it updates the dock icon to show the new icon.

The icon was changed by replacing the icon inside the .app/Contents/Resources folder then making a dummy folder at .app/Contents/dummy dir

Here's a youtube screencast showing it: https://www.youtube.com/watch?v=LFjjVbIXvbg

We see it also updates on keep in dock: https://www.youtube.com/watch?v=yZtmJVanmbw

Is there some objective-c function that is happening on these actions thats triggering the dock icon update? can you please help me to find that as i would love to do it this way rather then killall dock as that unminimizes all my windows.

thanks very much for your advice

Man Page

Simplify the usage function in favor of providing a man page.

Can't import plist as Domain User

Using a postinstall pkg script- dockutil is not installing an icon for the current logged in user:

The pkg succeeds but the log shows this error I get this on 10.8.5.

Dec 30 09:46:24 maccomp.global.domain.net.: ./postinstall: Sorry, user root is not allowed to execute '/usr/bin/defaults import /Users/grimml/Library/Preferences/com.apple.dock.plist /private/tmp/PKInstallSandbox.MXi7di/tmp/tmpKi7r0h' as grimml:LL\Domain Users on maccomp.global.domain.net.

Script:

!/bin/bash

Add My.app icons to existing users Dock

/usr/local/bin/dockutil --add '/Applications/Utilities/My.app' --allhomes

Sorry, user root is not allowed to execute '/usr/bin/defaults import /Users/grimml/Library/Preferences/com.apple.dock.plist /tmp/tmp4QBRZU' as grimml:LL\Domain Users on maccomp.global.domain.net.

Can you advise me on a solution?

Thanks very much

Flat application files placed next to document stacks instead of with applications

Best example of this is with Microsoft Office 2004. If you execute:

dockutil --add /Applications/Microsoft\ Office\ 2004/Microsoft\ Excel

The application is added to the right of the document stacks and immediately to the left of the Trash. Adding an --after flag and specifying an existing application makes no difference.

This does not occur with application bundles, for example:

dockutil --add /Applications/iTunes.app

This results in expected behavior.

feature request: network folder icons in the dock

Thanks for this useful utility.
I tested it on 10.8.2 and it works well for Applications.

But if I try to create an Folder-Icon pointing to an smb share, I get a strange behaviour.
The commands tested and its results:
(1)
dockutil --add 'smb:///' --display folder --label 'Share'
There is a new Icon, which looks like a spring with an "@" on top. When I click on it, the Finder opens with my smb share (first time I have to authenticate as expected).

But dockutil --list does not show the new item and I cannot remove it.
(but of course it can be removed with right click - remove from dock)

(2)
I created the Dock-Entry by dragging the mapped Folder from the Finder into the Dock.
Then it can be listed with dockutil --list as
'' file://localhost/Volumes/ persistent-others /Users....plist

Is it possible to fully implement the creation of network folders (smb, afp) in the Dock?
This would be very useful for our setup.

Regards, Bernhard

Super cool - thanks for this - is it possible to access non-persistent apps?

This is a really cool project you have. I was wondering is it possible to access dock icons that are not "Kept in Dock" (persisted)? I have an issue:

I created a desk.app on my Desktop. This desk.app runs a shell script to launch another application (Firefox). I have "kept in dock" this desk.app

So now click it launches Firefox, and all Firefox is icons all take the icon of desk.app, like window dialogs, and miniaturized windows. HOWEVER if I restart Firefox, it leaves my desk.app dock icon in the persistent section and now Firefox's actual logo pops up and is over in the non-persistent app section. I'm trying to remove that logo from non-persistent section and associate the Firefox application windows back to the desk.app icon I have persisting.

Can you please share your awesome wisdom on this subject on how I can fix this, programtically (as I do this from my firefox addon)

Running Dockutil at login through LaunchAgent doesn't work?

My problem is very straight forward: I'm trying to run commands for every user that logs in through using a LaunchAgent that runs a bash script:

#!/bin/bash
#/usr/bin/testing.sh

mkdir -p /Users/myname/Created


/usr/local/bin/dockutil --add "/Users/myname/Networks"
sudo dockutil --add "/usr/bin"
sudo dockutil --add "/usr/"
sudo dockutil --list > /Users/myname/Desktop/test.txt

In /Library/LaunchAgents/com.myname.test.plist :

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
        <key>Label</key>
        <string>com.sait.test.app</string>
        <key>ProgramArguments</key>
        <array>
                <string>/bin/sh</string>
                <string>/usr/bin/testing.sh</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>StandardOutPath</key>
        <string>/var/log/myjob.log</string>
        <key>Debug</key>
        <true/>

    </dict>
    </plist>

The folder is created on login. But, none of the DockUtil commands are executed. That is, my dock isn't changed and the test.txt doesn't contain any text. When I run these manually in the terminal, they work fine.

Why is this? Is there something that is wrong with how dock-util is loaded, or how it executes that I'm not aware of?