CLI Command Reference
Note
The better-timetagger-cli package installes two synonymous aliases: timetagger and t.
This documentation uses the longer alias timetagger for clarity, but you can abbreviate it to t in practice.
Note
There are command aliases for most commands.
For example: t show is synonymous with t display, report, and t ls.
And t start is synonymous with t check-in, t in, and t i.
Important
Review the help text for any command using the --help of -h flag.
timetagger
(Better) TimeTagger CLI
A feature-rich and ergonomic command-line interface for TimeTagger.
timetagger [OPTIONS] COMMAND [ARGS]...
Options
- --version
Show the version and exit.
app
Open the TimeTagger web app in the default browser.
In case the application fails to open the browser, the URL will be printed to the console.
Command aliases: ‘app’, ‘open’
timetagger app [OPTIONS]
diagnose
Check all records for common errors and inconsistencies.
Use the ‘–fix’ option with caution. This will modify the records in your database! It is recommended to back up your database before using this option.
Command aliases: ‘diagnose’
timetagger diagnose [OPTIONS]
Options
- -f, --fix
Apply fixes to corrupt records.
export
Export records to CSV format.
If no tags are provided, all tasks within the selected time frame will be included. Specify one or more tags to include only matching tasks.
The parameters ‘–start’ and ‘–end’ support natural language to specify date and time. You can use phrases like ‘yesterday’, ‘June 11’, ‘5 minutes ago’, or ‘05/12 3pm’.
Command aliases: ‘export’, ‘csv’
timetagger export [OPTIONS] [TAGS]...
Options
- -o, --output <file>
Output file. If not specified, print the output to stdout.
- -s, --start <start>
Include only records later than this time. Supports natural language.
- -e, --end <end>
Include only records earlier than this time. Supports natural language.
- -r, --round <round>
Round record times to a regular interval in minutes. Specify a value to round to that number of minutes (e.g., ‘–round 10’ for 10 minutes). If used as a flag without a value (e.g., ‘–round’), defaults to 5 minutes.
- -H, --hidden
Include only hidden (i.e. removed) records in the output.
- -R, --running
Include only running records in the output.
- -x, --match <tags_match>
Tag matching mode. Include records that match either ‘any’ or ‘all’ tags. Default: any.
- Options:
any | all
Arguments
- TAGS
Optional argument(s)
import
Import records to CSV format.
If no tags are provided, all tasks within the selected time frame will be included. Specify one or more tags to include only matching tasks.
The parameters ‘–start’ and ‘–end’ support natural language to specify date and time. You can use phrases like ‘yesterday’, ‘June 11’, ‘5 minutes ago’, or ‘05/12 3pm’.
Command aliases: ‘import’
timetagger import [OPTIONS] [TAGS]...
Options
- -f, --file <file>
Input file. If not specified, read CSV content from stdin.
- -s, --start <start>
Include only records later than this time. Supports natural language.
- -e, --end <end>
Include only records earlier than this time. Supports natural language.
- -n, --dry-run
Only display the records that would be imported. Do not actually import them to your TimeTagger instance.
- -x, --match <tags_match>
Tag matching mode. Include records that match either ‘any’ or ‘all’ tags. Default: any.
- Options:
any | all
Arguments
- TAGS
Optional argument(s)
remove
Hide TimeTagger records.
Specify one or more record keys to remove. To list record keys, use ‘t show –show-keys’.
This command marks records as ‘HIDDEN’ in the TimeTagger instance. This effectively removes them from view, but they can be restored later using the ‘t restore’ command.
Command aliases: ‘remove’, ‘hide’, ‘rm’
timetagger remove [OPTIONS] [KEYS]...
Arguments
- KEYS
Optional argument(s)
restore
Unhide TimeTagger records.
Specify one or more record keys to restore. To list hidden records and their keys, use ‘t show –hidden –show-keys’.
Command aliases: ‘restore’, ‘unhide’
timetagger restore [OPTIONS] [KEYS]...
Arguments
- KEYS
Optional argument(s)
resume
Start time tracking, using the same tags and description a recent record.
You may specify a tag, to only resume the most recent record that matches the tag.
The ‘–at’ parameter supports natural language to specify date and time. You can use phrases like ‘yesterday’, ‘June 11’, ‘5 minutes ago’, or ‘05/12 3pm’.
Note that only records from the last 4 weeks are considered.
Command aliases: ‘resume’, ‘r’
timetagger resume [OPTIONS] [TAGS]...
Options
- -a, --at <at>
Start the task at a specific time. Supports natural language.
- -k, --keep
Keep previous tasks running, do not stop them.
- -S, --select
Select a record to resume from a list of options.
- -v, --show-keys
List each record’s unique key. Useful to when you want to remove or restore records.
- -x, --match <tags_match>
Tag matching mode. Include records that match either ‘any’ or ‘all’ tags. Default: all.
- Options:
any | all
Arguments
- TAGS
Optional argument(s)
setup
Edit the configuration file for the TimeTagger CLI.
Command aliases: ‘setup’, ‘config’
timetagger setup [OPTIONS]
Options
- -e, --editor <editor>
The name or path of the editor you want to use. By default, the configuration file will be opened in the system’s default editor.
show
List tasks of the requested time frame.
If no tags are provided, all tasks within the selected time frame will be shown. Specify one or more tags to show only matching tasks.
The parameters ‘–start’ and ‘–end’ support natural language to specify date and time. You can use phrases like ‘yesterday’, ‘June 11’, ‘5 minutes ago’, or ‘05/12 3pm’.
Command aliases: ‘show’, ‘display’, ‘list’, ‘ls’, ‘d’
timetagger show [OPTIONS] [TAGS]...
Options
- -s, --start <start>
Include only records later than this time. Supports natural language.
- -e, --end <end>
Include only records earlier than this time. Supports natural language.
- -r, --round <round>
Round record times to a regular interval in minutes. Specify a value to round to that number of minutes (e.g., ‘–round 10’ for 10 minutes). If used as a flag without a value (e.g., ‘–round’), defaults to 5 minutes.
- -H, --hidden
Include only hidden (i.e. removed) records in the output.
- -R, --running
Include only running records in the output.
- -z, --summary
Show only the summary, disable table.
- -Z, --no-summary
Show only the table, disable summary.
- -f, --follow
Continuously monitor for changes and update the output in real time. If used with a relative ‘–start’ time (like ‘2 hours ago’), the monitored time frame will follow the current time.
- -v, --show-keys
List each record’s unique key. Useful to when you want to remove or restore records.
- -x, --match <tags_match>
Tag matching mode. Include records that match either ‘any’ or ‘all’ tags. Default: any.
- Options:
any | all
Arguments
- TAGS
Optional argument(s)
start
Start time tracking.
Provide one or more tags to label the task.
By default, previous tasks will be stopped automatically. Use ‘–keep’ to keep them running.
The ‘–at’ parameter supports natural language to specify date and time. You can use phrases like ‘yesterday’, ‘June 11’, ‘5 minutes ago’, or ‘05/12 3pm’.
Command aliases: ‘start’, ‘in’, ‘i’
timetagger start [OPTIONS] [TAGS]...
Options
- -a, --at <at>
Start the task at a specific time. Supports natural language.
- -d, --description <description>
Add a description to the task.
- -e, --empty
Allow starting a task without tags or description.
- -k, --keep
Keep previous tasks running, do not stop them automatically.
- -v, --show-keys
List each record’s unique key. Useful to when you want to remove or restore records.
Arguments
- TAGS
Optional argument(s)
status
Get an overview of today, this week and this month.
Command aliases: ‘status’
timetagger status [OPTIONS]
stop
Stop time tracking.
If no tags are provided, all running tasks will be stopped. Specify one or more tags to stop only matching tasks.
The ‘–at’ parameter supports natural language to specify date and time. You can use phrases like ‘yesterday’, ‘June 11’, ‘5 minutes ago’, or ‘05/12 3pm’.
Command aliases: ‘stop’, ‘out’, ‘o’
timetagger stop [OPTIONS] [TAGS]...
Options
- -a, --at <at>
Stop the task at a specific time. Supports natural language.
- -S, --select
Select a record to resume from a list of options.
- -v, --show-keys
List each record’s unique key. Useful to when you want to remove or restore records.
- -x, --match <tags_match>
Tag matching mode. Include records that match either ‘any’ or ‘all’ tags. Default: all.
- Options:
any | all
Arguments
- TAGS
Optional argument(s)