Post-Action Variables Guide

Learn how to use template variables and environment variables to dynamically reference file information in post-download actions.

⚡

Action Types

HarborDrop lets you configure automatic post-download actions per category. Automate file tagging, organization, notifications, and more using template variables to dynamically reference file information.

Add Tag	Attaches Finder tags to files. Use variables to auto-record domain, filename, etc.
Shell Script	Runs zsh scripts. Move files, rename, call external programs.
AppleScript	Runs macOS automation scripts. Use for Finder operations, notifications.
JavaScript	Runs JXA (JavaScript for Automation) scripts.

📋

Template Variables

Variables available in all action types (including tag addition).

%FILE_PATH%	Full path of downloaded file	/Users/me/Downloads/Video/movie.mp4
%FILE_NAME%	File name (with extension)	movie.mp4
%FILE_DIR%	Containing folder path	/Users/me/Downloads/Video
%FILE_STEM%	File name (without extension)	movie
%FILE_EXT%	File extension	mp4
%SOURCE_URL%	Full download URL	https://cdn.example.com/files/movie.mp4
%DOMAIN%	Download task domain	example.com
%SOURCE_DOMAIN%	Actual download URL host	cdn.example.com
%DATE_YYYYMMDD%	Download completion date	20260324
%UNIX_TS%	Unix timestamp	1774524055

%DOMAIN% vs %SOURCE_DOMAIN% Difference

When you download a video from example.com, the actual file comes from a CDN server (cdn.example.com). %DOMAIN% is the recognized task domain, while %SOURCE_DOMAIN% is the actual file server host. In most cases, they are identical.

🔄

Template vs Environment Variables

HarborDrop provides the same information in two formats. Choose the appropriate format based on your action type.

Template Variables

%FILE_NAME%

• Available in all action types
• Replaced with actual values before execution
• Only option for tag addition

Tag Addition Exampletext

Input tag: %DOMAIN%
    ↓ HarborDrop replaces
Actual tag: media.example.com

Environment Variables

$HARBORDROP_FILE_NAME

• Shell Script only
• Injected by the OS as variables
• Safe with special characters ($, `, ")

Shell Script Examplebash

Script: echo "$HARBORDROP_FILE_NAME"
    ↓ Shell reads at runtime
Output: My File (2026) $pecial.mp4

Which One Should I Use?

Action Type	Available	Recommended
Add Tag	Template only	%DOMAIN%, %FILE_NAME%
AppleScript	Template only	%FILE_PATH%
JavaScript	Template only	%FILE_PATH%
Shell Script	Both	Env vars recommended

💡

Why env vars are recommended for Shell Scripts: Template variables are inserted directly into the script text. If the filename is "My $100 File.mp4", $100 would be interpreted as a shell variable, causing errors. Environment variables don't have this issue.

🖥️

Environment Variables List

Environment variables available in Shell Scripts only. They hold the same values as their corresponding template variables.

$HARBORDROP_FILE_PATH	%FILE_PATH%	Full file path
$HARBORDROP_FILE_NAME	%FILE_NAME%	File name (with ext)
$HARBORDROP_FILE_DIR	%FILE_DIR%	Folder path
$HARBORDROP_FILE_STEM	%FILE_STEM%	File name (no ext)
$HARBORDROP_FILE_EXT	%FILE_EXT%	Extension
$HARBORDROP_SOURCE_URL	%SOURCE_URL%	Download URL
$HARBORDROP_DOMAIN	%DOMAIN%	Task domain
$HARBORDROP_SOURCE_DOMAIN	%SOURCE_DOMAIN%	Actual server host
$HARBORDROP_DATE_YYYYMMDD	%DATE_YYYYMMDD%	Completion date
$HARBORDROP_UNIX_TS	%UNIX_TS%	Unix timestamp

💡

Practical Examples

This feature is useful when multiple file types arrive in one category. For example, if pdf + zip + mp4 files all land in a "Lectures" category, you can keep pdfs as-is, auto-extract zips, and log mp4s separately.

Auto-Branch by Extensionbash

ext="${HARBORDROP_FILE_EXT:l}"
case "$ext" in
  pdf)
    # Keep documents as-is
    ;;
  zip)
    out="$HARBORDROP_FILE_DIR/$HARBORDROP_FILE_STEM"
    mkdir -p "$out"
    ditto -x -k "$HARBORDROP_FILE_PATH" "$out"
    ;;
  mp4|mkv|mov|webm)
    echo "$HARBORDROP_FILE_NAME" >> "$HOME/Downloads/video.log"
    ;;
esac

1. Record Source Site via Finder Tag

Action Type	Add Tag
Tag Name	%DOMAIN%

The source site name is automatically recorded as a Finder tag. Search by tag in Finder to quickly identify where files came from.

2. Auto-Organize Files by Date

Shell Scriptbash

dest="$HARBORDROP_FILE_DIR/$HARBORDROP_DATE_YYYYMMDD"
mkdir -p "$dest"
if mv -n "$HARBORDROP_FILE_PATH" "$dest/"; then
    echo "HARBORDROP_NEW_PATH=$dest/$HARBORDROP_FILE_NAME"
fi

💡

Output HARBORDROP_NEW_PATH=... on the last line to update the file path in HarborDrop's file list.

3. Auto-Organize Files by Domain

Shell Scriptbash

dest="$HARBORDROP_FILE_DIR/$HARBORDROP_DOMAIN"
mkdir -p "$dest"
if mv -n "$HARBORDROP_FILE_PATH" "$dest/"; then
    echo "HARBORDROP_NEW_PATH=$dest/$HARBORDROP_FILE_NAME"
fi

💡

You can achieve the same effect more simply by using %DOMAIN% directly in the category's download folder path. (e.g., ~/Downloads/Video/%DOMAIN%)

4. Download Complete Notification

AppleScriptapplescript

display notification "%FILE_NAME% downloaded" with title "HarborDrop" subtitle "%DOMAIN%"

5. Reveal File in Finder

JavaScript (JXA)javascript

var app = Application("Finder");
app.reveal(Path("%FILE_PATH%"));
app.activate();

6. Add Date Prefix to Filename

Shell Scriptbash

newname="${HARBORDROP_DATE_YYYYMMDD}_${HARBORDROP_FILE_NAME}"
newpath="$HARBORDROP_FILE_DIR/$newname"
if [ "$newpath" != "$HARBORDROP_FILE_PATH" ] && mv -n "$HARBORDROP_FILE_PATH" "$newpath"; then
    echo "HARBORDROP_NEW_PATH=$newpath"
fi

Before: lecture.pdf → After: 20260324_lecture.pdf

7. Auto-Optimize Images (ImageOptim)

Shell Scriptbash

if [[ "$HARBORDROP_FILE_EXT" =~ ^(png|jpg|jpeg|gif)$ ]]; then
    open -a "ImageOptim" "$HARBORDROP_FILE_PATH"
fi

8. Auto-Mount DMG Files

Shell Scriptbash

if [[ "$HARBORDROP_FILE_EXT" == "dmg" ]]; then
    hdiutil attach "$HARBORDROP_FILE_PATH" -nobrowse
fi

9. Log Download History to CSV

Shell Scriptbash

log="$HOME/Downloads/download_log.csv"

csv_escape() {
    local s="$1"
    s="${s//\"/\"\"}"
    printf '"%s"' "$s"
}

if [ ! -f "$log" ]; then
    echo "date,filename,domain,path" > "$log"
fi

echo "$(csv_escape "$HARBORDROP_DATE_YYYYMMDD"),$(csv_escape "$HARBORDROP_FILE_NAME"),$(csv_escape "$HARBORDROP_DOMAIN"),$(csv_escape "$HARBORDROP_FILE_PATH")" >> "$log"

10. Multiple Tags at Once

Create multiple tag addition actions in the category settings.

Tag ①	%DOMAIN%
Tag ②	Video
Tag ③	%DATE_YYYYMMDD%

Result: movie.mp4 (from media.example.com) → Finder tags: "media.example.com", "Video", "20260324"

📂

Path Change Notice

When you move or rename a file in a Shell Script, include the new path in the script output so HarborDrop's file list updates correctly.

echo "HARBORDROP_NEW_PATH=/new/path/to/file.mp4"

HarborDrop scans script output in reverse order (last line first) to find lines with the HARBORDROP_NEW_PATH= prefix. The file must actually exist at the specified path.

💡

Outputting on the last line is safest. While reverse scanning handles intermediate output, placing it last avoids confusion.

🔒

Security Notes

✅Tag addition always runs without any security settings.
🔐Shell Script / AppleScript / JavaScript requires enabling Settings > Security > Allow Advanced Scripts.

⚠️

Scripts may include filenames or URL content, so only configure scripts you trust.