Tim Time Tracker Help

Using Tim

Purchases

Scripting & Automation

You can control Tim with AppleScript, JavaScript, Shortcuts and URLs. Some actions need Pro, for example importing data or making more than 3 tasks.

AppleScript

To see all commands and their parameters, open Script Editor, choose File > Open Dictionary, then select Tim.

Commands that make a task, group or record return the ID of the new item as text. Most other commands take an ID.

Find items

-- Get the ID of a task from its title
tell application "Tim" to getTask "Task A"
--> "D43FA035-6406-495D-9ADD-46721986040F"

-- Get the ID of the running task. This gives an error if no timer is running.
tell application "Tim" to getActiveTask

Make tasks, groups and records

-- A task with only a title
tell application "Tim" to createTask title "Task B"

-- A task with notes, a group ID and tags (tag IDs or titles)
tell application "Tim" to createTask title "Task B" notes "Follow up Monday" group "9C1E5A80-2B77-4F0E-A0E1-1D7B6E2A9F31" tags {"Billed", "Urgent"}

-- A group
tell application "Tim" to createGroup title "Client X"
tell application "Tim" to createGroup title "Client X" notes "Retainer work"

-- A time record. Only the task is necessary. Without a start and end, Tim uses default times.
-- The date text must use the date format of your Mac.
tell application "Tim" to createRecord task "345287FA-CCF3-43E9-BC25-7AA68F7B88E7" ¬
    start date "10/25/24 9:00:00 AM" end date "10/25/24 10:15:30 AM" ¬
    notes "Worked" tags {"Billed"}

Control the timer

-- Start the timer for a task
tell application "Tim" to startTask "D43FA035-6406-495D-9ADD-46721986040F"

-- Stop the timer. This returns the ID of the new record.
-- It returns "" if Tim discarded the record because it was shorter than the minimum duration.
tell application "Tim" to stopTimer

-- Start or stop the timer. This returns the task ID.
tell application "Tim" to toggleTimer

-- Start the task that has the title "Task A"
tell application "Tim"
    set taskId to getTask "Task A"
    startTask taskId
end tell

Delete and archive

-- Delete a task and all of its records
tell application "Tim" to deleteTask "D43FA035-6406-495D-9ADD-46721986040F"

-- Delete a group, its tasks and all of their records
tell application "Tim" to deleteGroup "9C1E5A80-2B77-4F0E-A0E1-1D7B6E2A9F31"

-- Archive or unarchive a task or group.
-- An unarchived item moves to the top level of the list.
tell application "Tim" to archive "D43FA035-6406-495D-9ADD-46721986040F"
tell application "Tim" to unarchive "D43FA035-6406-495D-9ADD-46721986040F"

Import and export

-- Return all data as JSON text
tell application "Tim" to export

-- Replace all data with the data in a file
tell application "Tim" to import POSIX file "/path/to/file.json"

-- Add the data in a file to your current data. Returns true if the import worked.
tell application "Tim" to import POSIX file "/path/to/file.json" with merge

Open windows

tell application "Tim" to openTaskManager
tell application "Tim" to openNewTask
tell application "Tim" to openNavigator
tell application "Tim" to openActiveRecord

JavaScript for Automation

The same commands work in JavaScript. Use the command names in lowercase.

const tim = Application("Tim");

const data = tim.export();
tim.createtask({ title: "Task A" });
tim.createtask({ title: "Task B", tags: ["Billed"] });

const taskId = tim.gettask("Task A");
tim.createrecord({ task: taskId, start: new Date(), notes: "Worked" });

Command Line

Use osascript to send commands from Terminal or a shell script.

# Save all data to a file
osascript -e 'tell application "Tim" to export' > data.json

# Make a task with a tag
osascript -e 'tell application "Tim" to createTask title "Task B" tags {"Billed"}'

Shortcuts

Open the Shortcuts app, then select Tim in the Apps list. Tim has actions to make, find, archive and delete tasks and groups. There are also actions to start, stop and toggle the timer, make time records, and import or export your data.

Deep Links

We consider the create deep links deprecated and suggestion using AppleScript or Shortcuts.

x-callback-url

Tim supports the x-callback-url standard. The getCurrentUrl action gets the deep link of the item that is selected in Tim. Tim then opens your x-success URL, with the deep link in the url parameter and the item's name in the title parameter.

tim://x-callback-url/getCurrentUrl?x-success=https://example.com

Third-Party Integrations

Other developers made these tools.