Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Ebb

CLI for time tracking and flex time balance.

Features

  • Time tracking
  • Projects and tags
  • Flex time balance
  • Vacation, holiday, and sick day tracking

You can view help for any command with -h or --help (e.g., ebb balance --help). The command-line help lists every command and option.

Installation

Prebuilt Binaries

Each release has archives for Linux and macOS:

  • x86_64-unknown-linux-musl and aarch64-unknown-linux-musl for Linux, linked statically, so they run on any distribution
  • x86_64-apple-darwin and aarch64-apple-darwin for Intel and Apple Silicon Macs

Download the archive for your system from the releases page, verify that it was built from this repository, and unpack it:

version=v0.3.0
target=aarch64-apple-darwin
curl -LO "https://github.com/woylie/ebb/releases/download/$version/ebb-$version-$target.tar.gz"
gh attestation verify "ebb-$version-$target.tar.gz" --repo woylie/ebb
tar -xzf "ebb-$version-$target.tar.gz"

Without the GitHub CLI, you can compare the archive with the SHA256SUMS file of the release instead, using sha256sum -c --ignore-missing SHA256SUMS on Linux or shasum -a 256 -c --ignore-missing SHA256SUMS on macOS.

Then move the ebb binary to a directory on your PATH.

With Nix

nix profile install github:woylie/ebb/v0.3.0

If the binary can’t be found, ensure your Nix profile is in your PATH.

export PATH="$HOME/.nix-profile/bin:$PATH"

Manual Build

With Cargo:

git clone https://github.com/woylie/ebb.git --branch v0.3.0
cd ebb
cargo build --release
./target/release/ebb

With Nix:

nix build github:woylie/ebb/v0.3.0
./result/bin/ebb

Shell Completions

The Nix package includes completions for bash, fish and zsh. With any other installation, you can generate shell completions with:

ebb generate-completions --shell <SHELL>

To see a list of available shells, run:

ebb generate-completions --help

Configuration

You can list all available configuration options with:

ebb config list

Modify the defaults with:

ebb config set <KEY> <VALUE>

For example: ebb config set working_hours.monday 6h

  • sick_days_per_year.<YEAR> - Defines how many sick days you are allowed to take in a year. The value applies to the specified year and all subsequent years, until a new value is set for a later year.
  • vacation_days_per_year.<YEAR> - Specifies the number of vacation days allowed per year, starting from the given year. The value applies to the specified year and all subsequent years, until a new value is set for a later year.
  • working_hours.<WEEKDAY> - Defines how many hours you are supposed to work on a weekday. The value is a duration string, e.g. "6h" or "7h 30m".

Time Tracking

The commands related to time tracking are:

  • ebb start <PROJECT> [TAGS] - Start tracking time for the given project with optional tags. Tags are written as plain words, so ebb start website design review records the project website with the tags design and review. A project name or a tag that contains spaces has to be quoted, as in ebb start website "code review".
  • ebb stop - Stop tracking the current project.
  • ebb cancel - Cancel tracking without saving.
  • ebb restart - Restart the last project.
  • ebb status - Show the current time tracking status.

Reporting

  • ebb balance - Print the expected, actual and remaining work hours.
  • ebb report - Print a report listing the recorded time per project and tag.

Holidays, Vacation Days, and Sick Days

You can manage holidays, vacation days, and sick days with ebb holiday, ebb vacation, and ebb sickday. Run the commands without further arguments to see the command line help.

Holidays can be national holidays or other days on which you are not expected to work or log hours.

You can render an overview with the count of taken and remaining vacation days and sick days for the current year or other years with ebb daysoff or ebb daysoff --year 2024.

Important to Know

Vacation days, holidays, and sick days can be full or half days. This is relative to the expected working hours configured for that day. For example, if Monday is configured with 8 expected working hours, a full day off will reduce the expected working hours by 8 hours, and a half day off will reduce them by 4 hours. If a day is configured with 6 expected working hours, a full day off reduces them by 6 hours, and a half day off reduces them by 3 hours. This logic may be improved in the future based on user feedback.

Data Storage

Ebb keeps all data as TOML files in a single directory. The files can be read and edited with any text editor.

The default directory is ~/.local/share/ebb. If $XDG_DATA_HOME is set to an absolute path, the directory is $XDG_DATA_HOME/ebb.

You can choose a different directory by passing the --data-dir argument or by setting the EBB_DATA_DIR environment variable.

The files:

  • config.toml - The configuration.
  • frames.toml - The recorded time frames.
  • frames.toml.bak - Backup of the time frames. Ebb only keeps a single backup that is overwritten with every change.
  • state.toml - The currently running frame. When you stop a project or start a different project, this frame is written to frames.toml.
  • holidays.toml, sick_days.toml, vacations.toml - The days off.

If you want to back up your files, copy the whole directory:

cp -r ~/.local/share/ebb ~/backups/ebb-$(date +%Y-%m-%d)

Troubleshooting

Ebb returns an error if a data file is invalid. The error message includes the file name and the invalid value. Read the error message and fix the TOML file by hand.

If a project is counted twice, compare state.toml with the last entries in frames.toml and ensure that the entry in frames.toml ended before the entry in state.toml started. If both files contain the same time span, delete the wrong entry. Run ebb cancel to cancel the running frame.

If you made a mistake while editing frames.toml, you can restore the last version from the backup:

cp ~/.local/share/ebb/frames.toml.bak ~/.local/share/ebb/frames.toml

Note that Ebb overwrites the backup the next time data is changed.

Command-Line Help for ebb

This document contains the help content for the ebb command-line program.

Command Overview:

ebb

Usage: ebb [OPTIONS] <COMMAND>

Subcommands:
  • balance — Show working hour balance
  • cancel — Cancel the current time tracking frame
  • config — Manage the configuration
  • daysoff — Print overview of remaining vacation and sick days
  • holiday — Manage holidays
  • project — Manage projects
  • report — Return the total time and time spent per project
  • restart — Restart the last project
  • sickday — Manage sick days
  • start — Start time tracking
  • status — Show current time tracking status
  • stop — Stop time tracking
  • tag — Manage tags
  • vacation — Manage vacation days
Options:

  • -c, --data-dir <DATA_DIR> — Set the directory holding the configuration and the data; defaults to $XDG_DATA_HOME/ebb, or ~/.local/share/ebb when that is not set

  • -f, --format <FORMAT> — Set the output format

    Default value: text

    Possible values: text, json

ebb balance

Show working hour balance

Usage: ebb balance [OPTIONS]

Options:
  • --from <FROM> — First date (yyyy-mm-dd); for the current day, week, month or year, use –day, –week, –month or –year
  • --to <TO> — Last date, included (yyyy-mm-dd); for the current day, week, month or year, use –day, –week, –month or –year
  • -y, --year — Report time spent in the current year
  • -m, --month — Report time spent in the current month
  • -w, --week — Report time spent in the current week
  • -d, --day — Report time spent on the current day
  • --exclude-today — End at the start of the current day, counting only finished days

ebb cancel

Cancel the current time tracking frame

Usage: ebb cancel

ebb config

Manage the configuration

Usage: ebb config config <COMMAND>

Subcommands:
  • get — Get a single configuration value
  • list — List all configuration values
  • set — Set a configuration value

ebb config get

Get a single configuration value

Usage: ebb config get <KEY>

Arguments:
  • <KEY>

ebb config list

List all configuration values

Usage: ebb config list

ebb config set

Set a configuration value

Usage: ebb config set <KEY> <VALUE>

Arguments:
  • <KEY> — Configuration key
  • <VALUE> — Configuration value

ebb daysoff

Print overview of remaining vacation and sick days

Usage: ebb daysoff [OPTIONS]

Options:
  • -y, --year <YEAR> — Year; defaults to the current year

ebb holiday

Manage holidays

Usage: ebb holiday holiday <COMMAND>

Subcommands:
  • add — Add a new holiday
  • edit — Change the description and portion of an existing holiday
  • list — List all holidays
  • remove — Remove a holiday

ebb holiday add

Add a new holiday

Usage: ebb holiday add [OPTIONS] <DATE> [DESCRIPTION]

Arguments:
  • <DATE> — Date of the holiday (yyyy-mm-dd, e.g. 2025-08-11)
  • <DESCRIPTION> — Name of the holiday (e.g. Mountain Day); defaults to “Holiday”
Options:

  • -p, --portion <PORTION> — Switch between full-day and half-day holiday

    Default value: full

    Possible values: full, half

ebb holiday edit

Change the description and portion of an existing holiday

Usage: ebb holiday edit [OPTIONS] <DATE> <DESCRIPTION>

Arguments:
  • <DATE> — Date of the holiday to edit
  • <DESCRIPTION> — New name for the holiday
Options:

  • -p, --portion <PORTION> — New portion; omit to keep the current value

    Possible values: full, half

ebb holiday list

List all holidays

Usage: ebb holiday list [OPTIONS]

Options:
  • -y, --year <YEAR> — Filter by year

ebb holiday remove

Remove a holiday

Usage: ebb holiday remove <DATE>

Arguments:
  • <DATE> — Date of the holiday to remove

ebb project

Manage projects

Usage: ebb project project <COMMAND>

Subcommands:
  • list — List all projects
  • rename — Renames a project

ebb project list

List all projects

Usage: ebb project list

ebb project rename

Renames a project

Usage: ebb project rename <OLD_NAME> <NEW_NAME>

Arguments:
  • <OLD_NAME> — Current project name
  • <NEW_NAME> — New project name

ebb report

Return the total time and time spent per project

Usage: ebb report [OPTIONS]

Options:
  • --from <FROM> — Start date or time (yyyy-mm-dd, hh:mm, hh:mm:ss, yyyy-mm-dd hh:mm, yyyy-mm-dd hh:mm:ss, or ISO 8601); for the current day, week, month or year, use –day, –week, –month or –year
  • --to <TO> — End date or time (yyyy-mm-dd, hh:mm, hh:mm:ss, yyyy-mm-dd hh:mm, yyyy-mm-dd hh:mm:ss, or ISO 8601); a date includes that day; for the current day, week, month or year, use –day, –week, –month or –year
  • -y, --year — Report time spent in the current year
  • -m, --month — Report time spent in the current month
  • -w, --week — Report time spent in the current week
  • -d, --day — Report time spent on the current day
  • -p, --project <PROJECT> — Filter by project
  • -t, --tag <TAG> — Filter by tag

ebb restart

Restart the last project

Usage: ebb restart [OPTIONS]

Options:
  • --at <AT> — Time at which the project is restarted (hh:mm, hh:mm:ss, yyyy-mm-dd hh:mm, yyyy-mm-dd hh:mm:ss, or ISO 8601); if omitted, the current time is used
  • --ago <AGO> — How long ago the project was restarted, e.g. 30m or “1h 30m”; resolves to the time –at would name
  • -G, --no-gap — Set the start time to the end time of the last saved frame

ebb sickday

Manage sick days

Usage: ebb sickday sickday <COMMAND>

Subcommands:
  • add — Add one or more sick days
  • edit — Change the description and portion of an existing sick day
  • list — List all sick days
  • remove — Remove one or more sick days

ebb sickday add

Add one or more sick days.

A range spans at most a year. Days without working hours, full-day holidays and days that already have a sick day are skipped.

Usage: ebb sickday add [OPTIONS] <START_DATE> [END_DATE] [DESCRIPTION]

Arguments:
  • <START_DATE> — Start date (yyyy-mm-dd)
  • <END_DATE> — End date, inclusive (yyyy-mm-dd); defaults to the start date for a single day
  • <DESCRIPTION> — Description of the day off
Options:

  • -p, --portion <PORTION> — Switch between full-day and half-day

    Default value: full

    Possible values: full, half

ebb sickday edit

Change the description and portion of an existing sick day

Usage: ebb sickday edit [OPTIONS] <DATE> <DESCRIPTION>

Arguments:
  • <DATE> — Date of the sick day to edit
  • <DESCRIPTION> — New description for the sick day
Options:

  • -p, --portion <PORTION> — New portion; omit to keep the current value

    Possible values: full, half

ebb sickday list

List all sick days

Usage: ebb sickday list [OPTIONS]

Options:
  • -y, --year <YEAR> — Filter by year

ebb sickday remove

Remove one or more sick days.

A range spans at most a year.

Usage: ebb sickday remove <START_DATE> [END_DATE]

Arguments:
  • <START_DATE> — Start date (yyyy-mm-dd)
  • <END_DATE> — End date, inclusive (yyyy-mm-dd); defaults to the start date for a single day

ebb start

Start time tracking

Usage: ebb start [OPTIONS] <PROJECT> [TAGS]...

Arguments:
  • <PROJECT> — Name of the project
  • <TAGS> — Any number of additional tags; quote a tag that contains spaces
Options:
  • --at <AT> — Time at which the project is started and a running frame is stopped (hh:mm, hh:mm:ss, yyyy-mm-dd hh:mm, yyyy-mm-dd hh:mm:ss, or ISO 8601); if omitted, the current time is used
  • --ago <AGO> — How long ago the project was started, e.g. 30m or “1h 30m”; resolves to the time –at would name
  • -G, --no-gap — Set the start time to the end time of the last saved frame

ebb status

Show current time tracking status

Usage: ebb status

ebb stop

Stop time tracking

Usage: ebb stop [OPTIONS]

Options:
  • --at <AT> — Time at which the project is stopped (hh:mm, hh:mm:ss, yyyy-mm-dd hh:mm, yyyy-mm-dd hh:mm:ss, or ISO 8601); if omitted, the current time is used
  • --ago <AGO> — How long ago the project was stopped, e.g. 30m or “1h 30m”; resolves to the time –at would name

ebb tag

Manage tags

Usage: ebb tag tag <COMMAND>

Subcommands:
  • list — List all tags
  • remove — Remove a tag
  • rename — Renames a tag

ebb tag list

List all tags

Usage: ebb tag list

ebb tag remove

Remove a tag

Usage: ebb tag remove <TAG>

Arguments:
  • <TAG> — Name of the tag

ebb tag rename

Renames a tag

Usage: ebb tag rename <OLD_NAME> <NEW_NAME>

Arguments:
  • <OLD_NAME> — Current tag name
  • <NEW_NAME> — New tag name

ebb vacation

Manage vacation days

Usage: ebb vacation vacation <COMMAND>

Subcommands:
  • add — Add one or more vacation days
  • edit — Change the description and portion of an existing vacation day
  • list — List all vacation days
  • remove — Remove one or more vacation days

ebb vacation add

Add one or more vacation days.

A range spans at most a year. Days without working hours, full-day holidays and days that already have a vacation day are skipped.

Usage: ebb vacation add [OPTIONS] <START_DATE> [END_DATE] [DESCRIPTION]

Arguments:
  • <START_DATE> — Start date (yyyy-mm-dd)
  • <END_DATE> — End date, inclusive (yyyy-mm-dd); defaults to the start date for a single day
  • <DESCRIPTION> — Description of the day off
Options:

  • -p, --portion <PORTION> — Switch between full-day and half-day

    Default value: full

    Possible values: full, half

ebb vacation edit

Change the description and portion of an existing vacation day

Usage: ebb vacation edit [OPTIONS] <DATE> <DESCRIPTION>

Arguments:
  • <DATE> — Date of the vacation day to edit
  • <DESCRIPTION> — New name for the vacation day
Options:

  • -p, --portion <PORTION> — New portion; omit to keep the current value

    Possible values: full, half

ebb vacation list

List all vacation days

Usage: ebb vacation list [OPTIONS]

Options:
  • -y, --year <YEAR> — Filter by year

ebb vacation remove

Remove one or more vacation days.

A range spans at most a year.

Usage: ebb vacation remove <START_DATE> [END_DATE]

Arguments:
  • <START_DATE> — Start date (yyyy-mm-dd)
  • <END_DATE> — End date, inclusive (yyyy-mm-dd); defaults to the start date for a single day

This document was generated automatically by clap-markdown.