CLI time tracking utility. Mirror of https://git.andrewzah.com/andrewzah/faramir
Add --keep option for start, add util fns
Add note field to timer struct
run +nightly fmt


browse  log 



You can also use your local clone with git send-email.


Faramir gif

Faramir is a time tracking cli tool written in Rust, inspired by Watson.

Currently in alpha, so changes will occur.

All times are stored in UTC.


See commands below for more detailed information.

% faramir start demo_project -t tag1,tag2 -n "my custom note text"

Successfully started timer b0PQh7q1eqKc for project demo_project.

% faramir status

1 timer(s) found.
  Timer for project demo_project - with id b0PQh7q1eqKc
  Elapsed Time: 0w, 0d, 0h, 0m, 24s
  Start Time: 2020/01/05 21:32:10

% faramir stop
# or: faramir stop -i b0PQh7q1eqKc
Stopped timer b0PQh7q1eqKc.

% faramir ls projects
# or: faramir ls p
1 Project(s) found.

% faramir ls tags
% or: faramir ls ta
2 Tag(s) found.
tags: tag1, tag2

% faramir edit b0PQh7q1eqKc
# this opens a tmp json file with $EDITOR to edit

% faramir log
# all times are stored as UTC. this will become prettier!
1 timer(s) retrieved.
b0PQh7q1eqKc - start: 2020-01-05 21:32:10.579684938 UTC, end: 2020-01-05 21:34:30.199521260 UTC

% faramir rm timer b0PQh7q1eqKc
# or faramir rm t ...
# or faramir rm p(roject) ...
Successfully deleted timer b0PQh7q1eqKc.
  start: 2020-01-05 21:32:10.579684938 UTC, end: Some(2020-01-05T21:34:30.199521260Z)

todo (soon TM): commands for detailed reporting.


By default, faramir looks for $XDG_CONFIG_HOME. If this isn't set, it puts faramir-tt/ under $HOME/.config/.

A different config location can be specified with -c.

  "data_dir": "/home/andrew/.config/faramir-tt",
  "time_format": "%Y/%m/%d %H:%M:%S",
  "full_time_format": "%Y/%m/%d %H:%M:%.3f, Day %j, Week %U",
  "timezone": "America/New_York"
  • data_dir lets you put the actual faramir data (faramir.db, etc) in a different directory.
  • time_format is used for the add command.
  • full_time_format is used when the -d / --detailed flag is passed for some commands.
  • timezone is a standard timezone. Find yours here.


A Timer has an id, an rid (random id), a start (datetime<utc>) and end (datetime<utc>).

Projects and Tags have an id and a name.

Every Timer has a Project. Projects have many Timers.

A Timer can have multiple Tags. Tags have many Timers.

Associations are made through join tables, i.e. projects_timers and tags_timers.



Manually adds a timer. The format -s and -e use depends on your config's time_format parameter, but it still has to compile to a DateTime. So %Y.%m.%d %H:%M:%S works but %Y/%m/%d doesn't.

faramir add project1 -s "2020/01/04 21:50:00" -e "2020/01/04 21:51:00" -c
  • -s / --start
  • -e / --end
  • -t / --tags
  • -d / --duration => not implemented yet.


Generates autocompletions for your shell. The output is in your config's data_dir directory.

faramir completions zsh

Possible values: bash, fish, zsh, powershell, elvish


Edits a timer. Do not edit id or rid, because that'll cause issues in the database.

faramir edit ZFhSTQgU3GtH

You can see a timer's id whenever you create a timer, or run faramir log / faramir status, etc.

The $EDITOR environment variable must be set.


By default, retrieves a log of completed timers (that is, it doesn't include running timers).

% faramir log

3 timer(s) retrieved.
ZFhSTQgU3GtH - start: 2020-01-05 01:27:37.232082717 UTC, end: 2020-01-05 01:28:51.125580395 UTC
PZjIHmdC057W - start: 2020-01-05 02:50:00 UTC, end: 2020-01-05 02:51:00 UTC
3NsfWDtif6Sy - start: 2020-01-05 03:04:20.493443573 UTC, end: 2020-01-05 03:04:30.061320880 UTC
  • -l / --limit => 10 by default.

TODO: Add other qualifiers like date range, etc


List Projects or Tags.

% faramir ls projects

3 Project(s) found.
proj1, proj2, proj3
% faramir ls tags

3 Project(s) found.
tag1, tag2, tag3


Rename a Project or Tag.

% faramir rename p proj1 proj4

Successfully renamed project proj1 to proj4.

You can use p, project, or projects for the Project type. You can use t, tag, or tags for the Tag type.


Deletes a project, tag, or timer, and associated records.

faramir rm <type> <name/id>
% faramir rm p proj1

Project proj1 has 4 timers associated with it. Are you sure you want to remove it?
If so, type 'y'.

Successfully removed project proj1.
  • -y / --yes => Automatically deletes all related records. Dangerous!


Starts a timer at the current time, UTC.

This automatically creates the passed in project and tags. Tags are optional.

% faramir start proj5 -t tag3,tag4 -n "my note text here"

Successfully started timer Ga4SXq8XuZi1 for project proj5.

% faramir start -k
  • -k / --keep => Use the same project and tags as last time.


Displays the status of any running timers.

TODO: make this prettier.

% faramir status

1 timer(s) found.
timer for project proj5, with id Ga4SXq8XuZi1
  Elapsed Time: 0w, 0d, 0h, 1m, 23s
  Start Time: 2020/01/05 03:38:48
  • -d / --detailed => TODO: Show more detailed information like tags, etc.


Stops the timer if only 1 is running. Otherwise, use -i / --id to specify which timer.

% faramir stop

Stopped timer Ga4SXq8XuZi1.
  • -i / --id => Specify a timer manually if multiple are running.

There a few more planned commands.