Skip to content

Quick Start

A note about updates to this documentation

The documentation may undergo continuous changes since the project is under active development. There isn’t yet an automatic documentation creation pipeline—for now. Any help is appreciated!

This page will be a moment behind what you can find in the README on GitHub.



On Pypi you can find the package under the trakcli name.

You can install it with pip:

Terminal window
pip install trakcli

or with pipx:

Terminal window
pipx install trakcli




nix run github:lcfd/trak

Try the code locally

If you want to try the latest unpublished changes you can install locally the code in the repository by using Poetry and pipx.

Run poetry build and then

Terminal window
# x.x.x = The version you have used to do the build.
pipx install ./dist/trakcli-x.x.x-py3-none-any.whl

to install trak using the wheel file.


The package has the useful --help command that will explain all the commands.

The CLI will guide you anyway through what you should and must do with messages with specific messages.

Basic commands

To start using you can use those basic commands. They will create a project, run a session, get how is going, and stop the session.

Terminal window
# Create a project
trak create project <project-id>
# Start a session for a project
trak start <project-id>
# Check how the session is going on
trak status
# Stop the session
trak stop

Start a billable session for a project

trak start pasta -b

More on this:

Start a session for a project with a specific category

trak start pasta -c rigatoni

More on this:

But there is a lot more than that

All the commands are described in the help command:

trak --help


There is a dedicated command that ouputs clean strings for tools like Starship:

trak status -s or trak status --starship

To see the status in your terminal line open $HOME/.config/starship.toml and put this snippet inside of it:

Terminal window
command = """ trak status -s """
when = "trak status"
shell = "sh"