Skip to content

Configuration reference

Every setting ttd understands, with its type, default, and what it does. Each section below corresponds to a TOML table: the key billing.rounding lives in the config file as

[billing]
rounding = "up"

and can be changed from the command line with ttd config set billing.rounding up. See the Configuration guide for where settings live and how the layers interact.

[user]

Identity shown on your invoices.

name = ''

Your name, shown on invoices.

email = ''

Your email, shown on invoices.

address = ''

Your address, shown on invoices.

[business]

currency = 'USD'

Currency code for rates and invoices.

default_hourly_rate = None

Fallback hourly rate when client/project sets none.

[invoice]

number_format = '{year}-{seq:03d}'

Invoice number template; fields: {year}, {month}, {seq}.

payment_terms_days = 30

Days until an invoice is due.

tax_rate = Decimal('0')

Tax added to invoices, as a fraction (0.08 = 8%).

output_dir = Field(default=(Path('~/Documents/invoices')), validate_default=True)

Directory where rendered invoices are written.

[tax]

set_aside_rate = Decimal('0')

Fraction of each paid invoice's subtotal to set aside for taxes (0 disables).

[billing]

How logged time becomes billable time on invoices.

rounding = 'nearest'

How billable time rounds to the increment.

increment_minutes = 15

Billing increment in minutes.

[display]

time_format = '12h'

Clock format for displayed times.

week_start = 'monday'

First day of the week in reports.

theme = 'ttd-dark'

TUI theme name.

[parsing]

workday_start = 7

Workday start hour (0-23); disambiguates am/pm in parsed times.

workday_end = 19

Workday end hour (0-23); disambiguates am/pm in parsed times.

[defaults]

Fallbacks used when a command omits --client, --project, or --billable.

client = None

Client slug assumed when --client is omitted.

project = None

Project slug assumed when --project is omitted.

billable = True

Whether new entries are billable by default.

[storage]

db_path = None

SQLite database path (default: platform user-data dir).

Complete example

A global config file (~/.config/ttd/config.toml) showing every setting at its default value — you only ever need the keys you want to change:

[user]
name = ""                          # Your name, shown on invoices
email = ""                         # Your email, shown on invoices
address = ""                       # Your address, shown on invoices

[business]
currency = "USD"                   # Currency code for rates and invoices
# default_hourly_rate =            # Fallback rate when client/project sets none (unset)

[invoice]
number_format = "{year}-{seq:03d}" # Fields: {year}, {month}, {seq}
payment_terms_days = 30            # Days until an invoice is due
tax_rate = 0                       # Tax added to invoices, as a fraction (0.08 = 8%)
output_dir = "~/Documents/invoices"

[tax]
set_aside_rate = 0                 # Fraction of paid invoices to set aside (0 disables)

[billing]
rounding = "nearest"               # nearest | up | none
increment_minutes = 15             # Billing increment in minutes

[display]
time_format = "12h"                # 12h | 24h
week_start = "monday"              # monday | sunday
theme = "ttd-dark"                 # ttd-dark | ttd-light

[parsing]
workday_start = 7                  # Hour (0-23); disambiguates am/pm in parsed times
workday_end = 19

[defaults]
# client =                         # Client slug assumed when --client is omitted (unset)
# project =                        # Project slug assumed when --project is omitted (unset)
billable = true                    # Whether new entries are billable by default

[storage]
# db_path =                        # SQLite path (default: platform user-data dir)