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, t list, t ls, and t d.
Or t start is synonymous with t in, and t i
Important
Review the help text for any command using the --help of -h flag.
This will provide usage instructions along with a list of available options and arguments.
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.
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.
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. Tags can be entered without the leading hashtag ‘#’.
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’.
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. Tags can be entered without the leading hashtag ‘#’.
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’.
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.
- -z, --summary
Show only the summary, disable table.
- -Z, --no-summary
Show only the table, disable summary.
- -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)
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.
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’.
timetagger restore [OPTIONS] [KEYS]...
Arguments
- KEYS
Optional argument(s)
resume
Start time tracking, using the same tags and description of 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’.
By default, currently running tasks will be stopped automatically. Use ‘–keep’ to keep them running.
Note that only records from the last 4 weeks are considered.
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 automatically.
- -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.
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.
- -l, --list <list>
List all configuration options instead of opening the editor. Optionally provide a configuration key to list its value.
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. Tags can be entered without the leading hashtag ‘#’.
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’.
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. Tags can be entered without the leading hashtag ‘#’.
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’.
By default, currently running tasks will be stopped automatically. Use ‘–keep’ to keep them running.
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.
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. Tags can be entered without the leading hashtag ‘#’.
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’.
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)