AppleScript Commands and Examples

tell application "Timemator"
	-- idle, idle with task, paused, running manually or running autotracked
	get timer state
end tell

tell application id "com.catforce.timemator.macos"
	get timer running
end tell

tell application "Timemator"
	set theFolder to folder "Acme"
	set theTask to task "Design" of theFolder
	set theEntries to time entries of theTask
	set theState to timer state
	return {path of theTask, count of theEntries, theState}
end tell

tell application "Timemator"
	-- by name, anywhere in the list
	set theTask to task "Design"
	-- by name inside a folder
	set theTask to task "Design" of folder "Acme"
	-- by a whose clause: a list, which may be empty
	set activeDesignTasks to every task whose name is "Design" and archived is false
	-- by id: the same on every Mac that syncs your library
	set theId to id of theTask
	set sameTask to task id theId
	return path of sameTask
end tell

tell application "Timemator"
	set theTasks to every task whose archived is false
	set report to {}
	repeat with aTask in theTasks
		set trackedHours to (total duration of aTask) / 3600
		set end of report to (path of aTask) & ": " & (round (trackedHours * 10)) / 10 & " h"
	end repeat
	return report
end tell

tell application "Timemator"
	start timer for task "Design"
end tell

tell application "Timemator"
	-- a task inside a folder
	start timer for task "Design" of folder "Acme"
	-- with a note on the new time entry
	start timer for task "Design" with notes "Homepage mockups"
	-- by path: the folders and the task are created when they are missing
	set theTask to create task named "Acme/Design"
	start timer for theTask
	-- the command returns the time entry being tracked
	set theEntry to start timer for task "Design"
	return id of theEntry
end tell

tell application "Timemator"
	if current task is missing value then
		return "No current task."
	end if
	start timer
	return path of current task
end tell

tell application "Timemator"
	-- began ten minutes ago
	start timer for task "Design" at ((current date) - 10 * minutes)
end tell

tell application "Timemator"
	set wasRunning to pause timer
end tell

tell application "Timemator"
	-- end the entry five minutes ago, for example when your screen locked
	pause timer at ((current date) - 5 * minutes)
end tell

tell application "Timemator"
	set nowRunning to toggle timer
end tell

tell application "Timemator"
	if timer running then
		set theTask to current task
		set theEntry to current time entry
		set elapsedMinutes to round ((duration of theEntry) / 60)
		return (path of theTask) & ": " & elapsedMinutes & " min"
	else
		return "Nothing is being tracked."
	end if
end tell

tell application "Timemator"
	-- the exact state: idle, idle with task, paused, running manually, running autotracked
	set theState to timer state
	if theState is paused then
		return "Paused on " & (name of current task)
	else if theState is running autotracked then
		return "Auto-tracking " & (name of current task)
	end if
	return theState
end tell

tell application "Timemator"
	clear timer
end tell

set todayStart to current date
set time of todayStart to 0
set tomorrowStart to todayStart + 1 * days

tell application "Timemator"
	set todaysEntries to find time entries from todayStart to tomorrowStart
	set totalSeconds to 0
	repeat with anEntry in todaysEntries
		set totalSeconds to totalSeconds + (duration of anEntry)
	end repeat
	return {count of todaysEntries, totalSeconds / 3600}
end tell

set rangeEnd to current date
set rangeStart to rangeEnd - 7 * days

tell application "Timemator"
	-- everything from the last seven days
	set recentEntries to find time entries from rangeStart to rangeEnd
	-- one client: a folder stands for every task in it
	set acmeEntries to find time entries from rangeStart to rangeEnd in {folder "Acme"}
	-- two tasks
	set someEntries to find time entries from rangeStart to rangeEnd in {task "Design", task "Website"}
	-- unbilled entries only, archived tasks included
	set openEntries to find time entries from rangeStart to rangeEnd with billing status {unbilled} including archived true
	return {count of recentEntries, count of acmeEntries, count of someEntries, count of openEntries}
end tell

tell application "Timemator"
	set theEntries to time entries of task "Design"
	set report to {}
	repeat with anEntry in theEntries
		set startText to (begin date of anEntry) as text
		set durationMinutes to round ((duration of anEntry) / 60)
		set end of report to startText & ", " & durationMinutes & " min"
	end repeat
	return report
end tell

tell application "Timemator"
	-- the most recent entry
	set lastEntry to last time entry of task "Design"
	-- entries with notes
	set notedEntries to every time entry of task "Design" whose notes is not missing value
	-- billed entries
	set billedEntries to every time entry of task "Design" whose billing status is billed
	return {id of lastEntry, count of notedEntries, count of billedEntries}
end tell

set entryStart to current date
set time of entryStart to 9 * hours
set entryEnd to entryStart + 90 * minutes

tell application "Timemator"
	create time entry from entryStart to entryEnd in task "Design" with notes "Client call"
end tell

set entryStart to current date
set time of entryStart to 9 * hours
set entryEnd to entryStart + 90 * minutes

tell application "Timemator"
	-- the standard make command does the same
	make new time entry with properties {begin date:entryStart, end date:entryEnd, notes:"Client call"} at end of time entries of task "Design"
	-- already billed
	create time entry from entryStart to entryEnd in task "Design" billing status billed
	-- replace what overlaps the range, so an import can run again
	create time entry from entryStart to entryEnd in task "Design" with notes "Client call" replacing existing true
end tell

tell application "Timemator"
	set theEntry to last time entry of task "Design"
	set notes of theEntry to "Homepage mockups, round 2"
	set end date of theEntry to (begin date of theEntry) + 2 * hours
	set properties of theEntry to {notes:"Review", billing status:billed}
end tell

tell application "Timemator"
	set theEntry to last time entry of task "Design"
	set task of theEntry to task "Website"
end tell

tell application "Timemator"
	set billing status of (every time entry of task "Design" whose billing status is unbilled) to billed
end tell

-- Last month, every task of one client, marked as paid.
set thisMonthStart to current date
set time of thisMonthStart to 0
set day of thisMonthStart to 1
set lastMonthStart to thisMonthStart - 1 * days
set day of lastMonthStart to 1

tell application "Timemator"
	set openEntries to find time entries from lastMonthStart to thisMonthStart in {folder "Acme"} with billing status {unbilled, billed}
	repeat with anEntry in openEntries
		set billing status of anEntry to paid
	end repeat
	return count of openEntries
end tell

tell application "Timemator"
	set theEntries to time entries of task "Design"
	if (count of theEntries) < 2 then return "Nothing to merge."
	set mergedEntry to merge time entries {item 1 of theEntries, item 2 of theEntries}
	return duration of mergedEntry
end tell

tell application "Timemator"
	set theEntries to time entries of task "Design"
	if (count of theEntries) < 2 then return "Nothing to merge."
	-- keep the time between the entries, and put the result on another task
	merge time entries {item 1 of theEntries, item 2 of theEntries} into task "Website" filling gaps true
end tell

tell application "Timemator"
	set theEntry to last time entry of task "Design"
	if being tracked of theEntry then return "The entry is running; pause the timer first."
	delete theEntry
end tell

tell application "Timemator"
	-- every entry of a task that is shorter than a minute
	delete (every time entry of task "Design" whose duration < 60 and being tracked is false)
end tell

tell application "Timemator"
	set topLevel to root items
	set names to {}
	repeat with anItem in topLevel
		if class of anItem is folder then
			set end of names to (name of anItem) & "/"
		else
			set end of names to name of anItem
		end if
	end repeat
	return names
end tell

tell application "Timemator"
	-- every active task, with its path
	set activeTasks to every task whose archived is false
	set paths to path of every task
	-- the children of one folder, in display order
	set acmeTasks to tasks of folder "Acme"
	set acmeFolders to folders of folder "Acme"
	set acmeItems to nodes of folder "Acme"
	-- the tasks of one folder's subtree
	set theFolder to folder "Acme"
	set deeperTasks to every task whose parent folder is theFolder
	return {count of activeTasks, count of paths, count of acmeTasks, count of acmeFolders, count of acmeItems, count of deeperTasks}
end tell

tell application "Timemator"
	-- the folders Clients and Acme are created when missing, then the task Design
	set theTask to create task named "Clients/Acme/Design"
	return path of theTask
end tell

tell application "Timemator"
	-- a path that starts in a folder
	create task named "Acme/Design" in folder "Clients"
	-- the standard make command, with a color
	make new task with properties {name:"Website", color:teal, notes:"Relaunch"} at end of tasks of folder "Acme"
	-- at the top level
	make new task with properties {name:"Admin"}
end tell

tell application "Timemator"
	set theFolder to make new folder with properties {name:"Clients"}
	-- a folder inside a folder
	make new folder with properties {name:"Acme"} at end of folders of theFolder
end tell

tell application "Timemator"
	set theTask to task "Design"
	set name of theTask to "Design and Branding"
	set notes of theTask to "Contact: Jane Doe"
	set properties of theTask to {color:teal, notes:"Contact: Jane Doe"}
	return name of theTask
end tell

tell application "Timemator"
	set theFolder to folder "Acme"
	set parent folder of task "Design" to theFolder
	-- to the top level
	set parent folder of task "Website" to missing value
	-- first among its siblings
	set position of task "Website" to 1
end tell

tell application "Timemator"
	set billing of folder "Acme" to always billable
	set hourly rate setting of folder "Acme" to 120.0
	-- the task follows its folder
	set billing of task "Design" to inherited
	set hourly rate setting of task "Design" to missing value
	-- what applies
	return {billable of task "Design", hourly rate of task "Design"}
end tell

tell application "Timemator"
	archive task "Design"
end tell

tell application "Timemator"
	-- a folder with everything in it, moved to the top level like the menu item
	archive folder "Acme" moving to root true
	-- several at once
	archive {task "Design", task "Website"}
	-- every task that was not tracked in the last 90 days
	set cutoff to (current date) - 90 * days
	set staleTasks to every task whose archived is false and last tracked < cutoff
	if (count of staleTasks) > 0 then archive staleTasks
	-- and back
	unarchive task "Design"
end tell

tell application "Timemator"
	delete task "Website"
end tell

tell application "Timemator"
	-- a folder and everything in it
	delete folder "Acme"
	-- every archived task without any tracked time
	delete (every task whose archived is true and total duration is 0)
end tell

tell application "Timemator"
	set theRules to rule set of task "Design"
	if theRules is missing value then return "No rules."
	set report to {}
	repeat with aRule in rules of theRules
		set end of report to {kind of aRule, text of aRule, website url of aRule, application path of aRule}
	end repeat
	return {active of theRules, start behavior of theRules, start delay of theRules, report}
end tell

tell application "Timemator"
	set theRules to rule set of task "Design"
	if theRules is missing value then return "No rules."
	-- the combinations among the rules, and what each one combines
	set combinations to every rule of theRules whose kind is combination
	set report to {}
	repeat with aCombination in combinations
		set end of report to kind of every rule of aCombination
	end repeat
	-- the website rules only
	set websiteRules to every rule of theRules whose kind is website
	return {count of combinations, report, website url of every rule of theRules}
end tell

tell application "Timemator"
	-- one task's rules; a task without rules refuses with error 10008
	if rule set of task "Design" is not missing value then
		set auto tracking of task "Design" to false
	end if
	-- auto-tracking as a whole
	set auto tracking enabled to false
end tell

tell application "Timemator"
	set todaySummary to get time summary scope daily
	set totalMinutes to round ((total duration of todaySummary) / 60)
	return "Today: " & (totalMinutes div 60) & " h " & (totalMinutes mod 60) & " min"
end tell

tell application "Timemator"
	-- yesterday
	set yesterdaySummary to get time summary scope daily on ((current date) - 1 * days)
	-- this month, one client only, unbilled entries
	set monthSummary to get time summary scope monthly in {folder "Acme"} with billing status {unbilled}
	return {total duration of yesterdaySummary, total revenue of monthSummary, time entry count of monthSummary}
end tell

tell application "Timemator"
	set weekSummary to get time summary scope weekly
	set report to {}
	repeat with aTotal in task totals of weekSummary
		set taskMinutes to round ((duration of aTotal) / 60)
		set end of report to (path of (task of aTotal)) & ": " & taskMinutes & " min"
	end repeat
	return report
end tell

-- A custom period: the last 14 days.
set rangeEnd to current date
set rangeStart to rangeEnd - 14 * days

tell application "Timemator"
	set customSummary to get time summary from rangeStart to rangeEnd
	return {begin date of customSummary, end date of customSummary, total duration of customSummary}
end tell

set rangeEnd to current date
set time of rangeEnd to 0
set rangeStart to rangeEnd - 7 * days
set outputPath to (POSIX path of (path to desktop)) & "Timemator last 7 days.csv"

tell application "Timemator"
	export time entries from rangeStart to rangeEnd to file (POSIX file outputPath) as CSV
end tell

set rangeEnd to current date
set time of rangeEnd to 0
set rangeStart to rangeEnd - 7 * days
set outputPath to (POSIX path of (path to desktop)) & "Acme unbilled.csv"

tell application "Timemator"
	-- one client, unbilled entries, comma-separated, without the rounding columns
	export time entries from rangeStart to rangeEnd to file (POSIX file outputPath) as CSV in {folder "Acme"} with billing status {unbilled} delimiter comma including roundings false
	-- the entries of archived tasks too; they are left out otherwise
	export time entries from rangeStart to rangeEnd to file (POSIX file outputPath) as CSV including archived true
	-- the same, and mark the exported entries as billed afterwards
	export time entries from rangeStart to rangeEnd to file (POSIX file outputPath) as CSV in {folder "Acme"} with billing status {unbilled} marking as billed true
end tell

set monthStart to current date
set time of monthStart to 0
set day of monthStart to 1
set monthEnd to current date
set outputPath to (POSIX path of (path to desktop)) & "Timemator this month.pdf"

tell application "Timemator"
	export time entries from monthStart to monthEnd to file (POSIX file outputPath) as PDF group by task duration format decimal
end tell

-- Today, from midnight to midnight
set todayStart to current date
set time of todayStart to 0
set todayEnd to todayStart + 1 * days

-- This week, starting on Monday
set daysSinceMonday to ((weekday of todayStart) as integer) - 2
if daysSinceMonday < 0 then set daysSinceMonday to 6
set weekStart to todayStart - daysSinceMonday * days
set weekEnd to weekStart + 7 * days

-- Last week
set lastWeekStart to weekStart - 7 * days
set lastWeekEnd to weekStart

-- This month
set monthStart to todayStart
set day of monthStart to 1
set nextMonthStart to monthStart + 32 * days
set day of nextMonthStart to 1

-- Last month
set lastMonthStart to monthStart - 1 * days
set day of lastMonthStart to 1

-- A fixed date, built from its parts so it works in every language
set fixedDate to current date
set time of fixedDate to 0
set day of fixedDate to 1
set year of fixedDate to 2026
set month of fixedDate to 3
set day of fixedDate to 15

return {todayStart, weekStart, lastWeekStart, monthStart, lastMonthStart, fixedDate}

set todayStart to current date
set time of todayStart to 0
set rightNow to current date

tell application "Timemator"
	set todaysRecords to find activity records from todayStart to rightNow
	set report to {}
	repeat with aRecord in todaysRecords
		set end of report to {application name of aRecord, title of aRecord, round ((duration of aRecord) / 60)}
	end repeat
	return report
end tell

set rangeEnd to current date
set rangeStart to rangeEnd - 7 * days

tell application "Timemator"
	-- one app, by its bundle identifier
	set safariRecords to find activity records from rangeStart to rangeEnd with bundle identifier "com.apple.Safari"
	-- several apps
	set officeRecords to find activity records from rangeStart to rangeEnd with bundle identifier {"com.apple.iWork.Pages", "com.apple.iWork.Numbers"}
	-- the websites of the last seven days
	set visited to {}
	repeat with aRecord in safariRecords
		if website url of aRecord is not missing value then set end of visited to website url of aRecord
	end repeat
	return {count of officeRecords, visited}
end tell

set todayStart to current date
set time of todayStart to 0
set yesterdayStart to todayStart - 1 * days

tell application "Timemator"
	set theRecords to find activity records from yesterdayStart to todayStart with bundle identifier "com.apple.Safari"
	set deletedCount to 0
	repeat with aRecord in theRecords
		if recording of aRecord is false then
			delete aRecord
			set deletedCount to deletedCount + 1
		end if
	end repeat
	return deletedCount
end tell

set todayStart to current date
set time of todayStart to 0
set yesterdayStart to todayStart - 1 * days

tell application "Timemator"
	delete (every activity record whose bundle identifier is "com.apple.Safari" and begin date ≥ yesterdayStart and begin date < todayStart and recording is false)
end tell

tell application "Timemator"
	set theItem to selected item
	if theItem is missing value then return "Nothing is selected."
	if class of theItem is time entry then
		return "Time entry on " & (path of task of theItem)
	else
		return path of theItem
	end if
end tell

tell application "Timemator"
	show task "Design"
	activate
end tell

tell application "Timemator"
	show folder "Acme"
	show last time entry of task "Design"
end tell

tell application "Timemator"
	open reports scope weekly
	activate
end tell

tell application "Timemator"
	-- last month
	open reports scope monthly on ((current date) - 30 * days)
end tell

set dayStart to current date
set time of dayStart to 0
set dayEnd to dayStart + 1 * days

tell application "Calendar"
	set theEvents to every event of calendar "Work" whose start date ≥ dayStart and start date < dayEnd
	set eventList to {}
	repeat with anEvent in theEvents
		set end of eventList to {summary of anEvent, start date of anEvent, end date of anEvent}
	end repeat
end tell

tell application "Timemator"
	set theTask to create task named "Meetings"
	repeat with anEvent in eventList
		set {eventTitle, eventStart, eventEnd} to anEvent
		create time entry from eventStart to eventEnd in theTask with notes eventTitle replacing existing true
	end repeat
	return count of eventList
end tell

tell application "Things3"
	set selectedToDos to selected to dos
	if (count of selectedToDos) is 0 then return "Select a to-do in Things first."
	set theTitle to name of item 1 of selectedToDos
end tell

tell application "Timemator"
	set theTask to create task named ("Things/" & theTitle)
	start timer for theTask
	return path of theTask
end tell

-- TODO: not tested; OmniFocus was not available while this page was written.
tell application "OmniFocus"
	set selectedTrees to selected trees of content of first document window of front document
	if (count of selectedTrees) is 0 then return "Select a task in OmniFocus first."
	set theTitle to name of value of item 1 of selectedTrees
end tell

tell application "Timemator"
	set theTask to create task named ("OmniFocus/" & theTitle)
	start timer for theTask
	return path of theTask
end tell

set dayEnd to current date
set time of dayEnd to 0
set dayStart to dayEnd - 1 * days

set yearText to (year of dayStart) as text
set monthText to text -2 thru -1 of ("0" & ((month of dayStart) as integer))
set dayText to text -2 thru -1 of ("0" & (day of dayStart))
set reportFolder to (POSIX path of (path to documents folder)) & "Timemator Reports/"
do shell script "mkdir -p " & quoted form of reportFolder
set outputPath to reportFolder & yearText & "-" & monthText & "-" & dayText & ".csv"

tell application "Timemator"
	export time entries from dayStart to dayEnd to file (POSIX file outputPath) as CSV delimiter comma
end tell

<?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.example.timemator-daily-report</string>
	<key>ProgramArguments</key>
	<array>
		<string>/usr/bin/osascript</string>
		<string>/Users/YOUR-USER-NAME/Library/Scripts/Applications/Timemator/Daily Report.scpt</string>
	</array>
	<key>StartCalendarInterval</key>
	<dict>
		<key>Hour</key>
		<integer>7</integer>
		<key>Minute</key>
		<integer>0</integer>
	</dict>
</dict>
</plist>

# start, pause, toggle
osascript -e 'tell application "Timemator" to start timer for task "Design"'
osascript -e 'tell application "Timemator" to pause timer'
osascript -e 'tell application "Timemator" to toggle timer'

# what is running
osascript -e 'tell application "Timemator"' -e 'if timer running then return path of current task' -e 'return "idle"' -e 'end tell'

# a saved script
osascript ~/Library/Scripts/Applications/Timemator/Start\ Design.scpt

# TODO: not tested; JXA is not covered by Timemator's own tests
osascript -l JavaScript -e 'Application("Timemator").timerRunning()'

on run {input, parameters}
	set taskPath to (item 1 of input) as text
	tell application "Timemator"
		set theTask to create task named taskPath
		start timer for theTask
		return path of theTask
	end tell
end run

#!/bin/bash
# Save as timemator.1m.sh in your SwiftBar or xbar plugin folder and make it executable.
osascript <<'EOF'
tell application "System Events"
	set timematorIsRunning to (count of (processes whose bundle identifier is "com.catforce.timemator.macos")) > 0
end tell
if not timematorIsRunning then return "Timemator off"
tell application "Timemator"
	if timer running then
		set elapsedMinutes to round ((duration of current time entry) / 60)
		return (name of current task) & " " & elapsedMinutes & " min"
	else if current task is missing value then
		return "Timemator idle"
	else
		return (name of current task) & " paused"
	end if
end tell
EOF

try
	tell application "Timemator"
		start timer for task "Design"
	end tell
on error errorMessage number errorNumber
	if errorNumber is 10003 then
		display alert "The task is archived." message errorMessage
	else if errorNumber is -1728 then
		display alert "There is no task called Design."
	else if errorNumber is -1743 then
		display alert "Timemator may not be controlled by this app." message "Allow it under System Settings › Privacy & Security › Automation."
	else
		display alert "Timemator reported error " & errorNumber message errorMessage
	end if
end try

if application "Timemator" is running then
	tell application "Timemator"
		return timer running
	end tell
else
	return "Timemator is not running."
end if

tell application "System Events"
	set timematorIsRunning to (count of (processes whose bundle identifier is "com.catforce.timemator.macos")) > 0
end tell

tell application "Timemator"
	if read only then
		return "Timemator is in read-only mode; nothing can be changed."
	end if
	start timer for task "Design"
end tell

tell application "Timemator"
	if scripting version < 1 then
		return "This script needs a newer Timemator."
	end if
	return {scripting version, version}
end tell