Task Finished Dock Badge: How to Set It Up

Yes, you can send a notification badge to the terminal dock icon when a task finishes, and this guide shows you exactly how to do it on macOS. You’ll learn the built-in Terminal method, a no-install approach using AppleScript, and how to make it work with any command-line task. The key is using the osascript command to update the dock icon’s badge label, which works with the standard Terminal app and most third-party terminals.

Why a Dock Badge for Task Completion?

When you run long tasks in the terminal—like data downloads, video encoding, or software builds—you often can’t watch the window continuously. A dock badge gives you a visual cue without needing to check the terminal window. The badge appears as a red circle with a number or short text on the Terminal icon in the Dock, and it stays until you click the icon or clear it manually. This is especially useful if you have multiple desktops or workspaces and the terminal is on another screen.

How the Badge Mechanism Works

macOS provides a private AppleScript command that sets the badge label of any application’s dock icon. The command is osascript -e 'tell application "Terminal" to set badge label of window 1 to "Done"'. This works because the Terminal app (and many other apps) exposes a badge label property through AppleScript. When you run this command from within a shell script, it tells the Terminal application to update its dock icon with the text you specify. The badge appears as a small red bubble with your text (limited to a few characters). It does not require any third-party software, and it works on macOS versions that support AppleScript (essentially all modern versions).

To use it after a task finishes, you simply append the osascript command to your original command, separated by a semicolon or using && if you want it to run only on success. For example:

long_running_task && osascript -e 'tell application "Terminal" to set badge label of window 1 to "Done"'

If you want the badge to appear regardless of the task’s exit status (even if it fails), use a semicolon instead:

long_running_task; osascript -e 'tell application "Terminal" to set badge label of window 1 to "Finished"'

Setting It Up in Terminal (Step-by-Step)

1. Open the Terminal app (found in /Applications/Utilities/).
2. Run a test command to ensure the badge works: type osascript -e 'tell application "Terminal" to set badge label of window 1 to "Test"' and press Enter. You should see a red badge with “Test” on the Terminal dock icon.
3. Clear the badge by setting it to an empty string: osascript -e 'tell application "Terminal" to set badge label of window 1 to ""'.
4. Now, run your actual long task with the badge command appended. For example: ping -c 100 google.com && osascript -e 'tell application "Terminal" to set badge label of window 1 to "Ping Done"'. This will ping 100 times, then set the badge.
5. To make the badge disappear automatically when you click the terminal icon, you can add a command to clear it in your shell profile or use a wrapper script. A simple way is to use a function in your ~/.bashrc or ~/.zshrc that wraps commands and clears the badge when the terminal gains focus (though this requires a bit more scripting).

Using It with Third-Party Terminals

The badge command works with any application that supports the AppleScript badge label property. For third-party terminals like iTerm2, you can replace “Terminal” with the application name. For example:

osascript -e 'tell application "iTerm2" to set badge label of current window to "Done"'

However, not all terminals support this property. If you use a terminal that doesn’t, you have two options: use the standard Terminal app for tasks where you need the badge, or use a terminal that supports custom badge scripts (like iTerm2’s “Badge” feature, which is separate from the dock badge). The dock badge approach is limited to apps that expose the property, so test it with your terminal first.

Common Problems and How to Fix Them

• Badge doesn’t appear: Make sure you’re using the correct application name in the tell statement. Run osascript -e 'id of app "Terminal"' to get the bundle ID, and use that if the name fails.
• Badge shows “Cannot compute” or an error: This often happens if the window reference is wrong. Use window 1 for the frontmost window, or front window to be safe.
• Badge text is too long: macOS truncates the badge to a few characters (usually around 5). Use short labels like “Done”, “OK”, or “Fail”.
• Badge stays after task completes: That’s expected. To clear it manually, run the command with an empty string. To automate clearing when you click the icon, you can use a tool like Hammerspoon or write a small AppleScript that runs on app activation, but that’s beyond the scope of a simple command.

Alternatives to Dock Badges

If the dock badge isn’t enough, you have other notification options:

• Notification Center alerts: Use osascript -e 'display notification "Task done" with title "Terminal"' to show a banner. This is more noticeable and can include a sound.
• Sound alerts: Play a system sound with afplay /System/Library/Sounds/Glass.aiff after the task.
• Growl or similar: While Growl is deprecated, you can use terminal-notifier (a command-line tool) to send rich notifications.
• Shell integration: Some terminals like iTerm2 have built-in “Notify on next line” features that pop a notification when a command finishes.

Frequently Asked Questions

Does this work on macOS Sonoma or Sequoia?

Yes, the AppleScript badge command works on all recent macOS versions, including Sonoma and Sequoia. Apple hasn’t removed the property, and it’s still supported in Terminal.

Can I set a badge with a number, like the count of errors?

Yes, you can set any short string, including a number. For example, set badge label to "3" will show a red badge with the number 3. You can compute the number in your script and pass it to the command.

Will the badge appear if the terminal window is closed?

No, the badge is tied to the window. If you close the window, the badge disappears. To keep it, you need to keep the window open.

Can I use this in a script that runs in the background?

Yes, you can run the osascript command from any shell script, even if it’s in the background. The command will update the dock icon as long as the Terminal app is running.

Is there a way to make the badge clear automatically when I click the icon?

Not without extra scripting. You can create an AppleScript that runs on app activation and clears the badge, but that requires a separate script or a tool like Hammerspoon. The simplest approach is to clear it manually with the empty string command.

Does this work with other apps, like Finder?

Yes, you can set the badge for any app that supports the property, but it’s not universal. Finder, for example, does not support it. Terminal and iTerm2 do, which covers most command-line needs.

Related

• Galaxy S9 Iris Scanner: Does It Have One?
• Expand RAID5 Partition: How to Do It Safely
• IPTV USA: Compare Channels, Costs & Devices