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.
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’, ‘diag’
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, output to stdout.
- -s, --start <start>
Include records later than this time. Supports natural language.
- -e, --end <end>
Include records earlier than this time. Supports natural language.
- -r, --round <round>
Round records to the nearest N minutes. Default: 5 minutes.
- -H, --hidden
List only hidden (i.e. removed) records in the output.
- -R, --running
List only running records in the output.
- -x, --match <tags_match>
Tag matching mode. Include records that match 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, imports from stdin.
- -s, --start <start>
Include records later than this time. Supports natural language.
- -e, --end <end>
Include records earlier than this time. Supports natural language.
- -n, --dry-run
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 any or all tags. Default: any.
- Options:
any | all
Arguments
- TAGS
Optional argument(s)
remove
Hide TimeTagger records.
Specify one or more keys of records to remove from view. To list record keys, use ‘t show –show-keys’.
Note that this command marks records as ‘HIDDEN’ in the TimeTagger database. This effectively removes them from view, but they can be restored if necessary.
To list hidden records, use ‘t show –hidden’.
Restore hidden records with ‘t restore’.
Command aliases: ‘remove’, ‘hide’, ‘rm’
timetagger remove [OPTIONS] [KEYS]...
Arguments
- KEYS
Optional argument(s)
restore
Unhide TimeTagger records.
Specify one or more keys of records to restore. To list hidden record 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’, ‘continue’, ‘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
Show a list of matching records to select from.
- -v, --show-keys
List each record’s key.
- -x, --match <tags_match>
Tag matching mode. Find records that match 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’, ‘init’
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’, ‘report’, ‘display’, ‘list’, ‘ls’, ‘d’
timetagger show [OPTIONS] [TAGS]...
Options
- -s, --start <start>
Show records later than this time. Supports natural language.
- -e, --end <end>
Show records earlier than this time. Supports natural language.
- -r, --round <round>
Round records to the nearest N minutes. Default: 5 minutes.
- -H, --hidden
List only hidden (i.e. removed) records in the output.
- -R, --running
List only running records in the output.
- -z, --summary
Show only summary, disable table.
- -Z, --no-summary
Show table only, 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 moniroted time frame will follow the current time.
- -v, --show-keys
List each record’s key.
- -x, --match <tags_match>
Tag matching mode. Filter records that match 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.
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’, ‘check-in’, ‘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.
- -v, --show-keys
List each record’s key.
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’, ‘check-out’, ‘out’, ‘o’
timetagger stop [OPTIONS] [TAGS]...
Options
- -a, --at <at>
Stop the task at a specific time. Supports natural language.
- -S, --select
Show a list of matching records to select from.
- -v, --show-keys
List each record’s key.
- -x, --match <tags_match>
Tag matching mode. Find records that match any or all tags. Default: all.
- Options:
any | all
Arguments
- TAGS
Optional argument(s)