timew

Start tracking an activity

$ timew start

$ timew tag [activity_tag]

$ timew start [activity_tag]

$ timew stop

$ timew track [start_time] - [end_time] [activity_tag]

$ timew summary

$ timew summary :[today|yesterday|week|lastweek|month|lastmonth|year|lastyear]

timew [options] [arguments...]

start [tags...]
    Begins tracking time for a task, optionally with descriptive tags. For example, timew start project:task meeting.

stop [id|tags...]
    Stops the currently active time tracking, or a specific entry using its ID or matching tags.

track [tags...]
    Adds a past time entry of a specified duration (e.g., 15min, 2h), with optional tags.

summary [filters...]
    Generates a summarized report of time entries based on specified filters (e.g., :day, :week, project:alpha).

gaps [filters...]
    Identifies and displays periods of untracked time within a specified range or filters.

annotate [tags...]
    Adds or modifies tags and descriptions for an existing time entry identified by its ID.

tags
    Lists all unique tags used across your time entries, providing an overview of your activity categories.

export [filters...]
    Exports time data in a machine-readable format (e.g., JSON), useful for backups or integrations.

import
    Imports time data from a file, allowing for data migration or restoration.

undo
    Reverts the last modification made to time entries, providing a safety net for errors.

config [name [value]]
    Manages Timewarrior configuration settings, allowing customization of behavior and output.

extensions
    Lists available extensions and their status, enabling enhanced functionality.

help [command]
    Displays comprehensive help information for Timewarrior or a specific subcommand.

Timewarrior (timew) is a powerful, lightweight command-line utility for tracking time spent on tasks or projects. It allows users to record, annotate, and analyze time entries directly from the terminal.

Designed for efficiency and privacy, timew stores all data locally in plain text files, ensuring complete control over your information. It supports a wide range of features, including starting and stopping timers, logging past entries, adding tags, and generating detailed reports based on sophisticated query filters. Its extensibility through hooks and extensions makes it a versatile tool for personal and professional time management.

Timewarrior is primarily a command-line tool, which might present a learning curve for users unfamiliar with terminal interfaces or its specific query syntax. While its local data storage enhances privacy, it means there is no built-in cloud synchronization; users needing multi-device access must implement their own syncing solutions (e.g., using `git` or `rsync`).

All timew data is stored locally in plain-text files, typically located in ~/.timewarrior. This design choice prioritizes user privacy and control, making data easy to backup, inspect, and manually edit if necessary.

Timewarrior supports a powerful hook system, allowing users to execute custom scripts (written in any language) before or after certain commands. This enables deep customization, integration with other tools, or automated actions based on time-tracking events.

Timewarrior was developed by the same team behind Taskwarrior, a popular command-line task management tool. It emerged from a desire to provide a dedicated, robust, and accurate time-tracking solution that integrates well with Taskwarrior's philosophy. First publicly released around 2016, it has since grown into a stable and actively maintained project, focusing on precision, flexibility, and extensibility.

task(1), at(1)