weekly

Track Activities using Google Calendar

Track your (weekly) activities using Google Calendar.

Here's a teaser:

$ weekly ls --aggregate weekly --days 5
┌──────────────────┬────────┬──────────┬──────────┬──────┬─────────┐
│    START TIME    │ HOURS  │ PROJECT  │ ACTIVITY │ TAGS │ PERSONS │
├──────────────────┼────────┼──────────┼──────────┼──────┼─────────┤
│ 2025-11-17 00:00 │ 8.2    │ nexa     │          │      │         │
│ 2025-11-17 00:00 │ 16.0   │ mlab     │          │      │         │
│ 2025-11-22 00:00 │ 1.0    │ personal │          │      │         │
└──────────────────┴────────┴──────────┴──────────┴──────┴─────────┘

See sessionexample.md for an example of a typical user session. See tutorial.md for details about how to format your calendar entries using several output formats (including JSON and CSV).

Install

1. You need Go >= 1.25

2. Install this tool

go install github.com/bassosimone/weekly@latest

First-Time Setup

The following instructions assume that

if [[ -n $XDG_CONFIG_HOME ]]; then
	export configDir=$XDG_CONFIG_HOME/weekly
else
	export configDir=$HOME/.config/weekly
fi

1. Create a project in Google Cloud Engine (e.g., weekly)

2. Create a service account with no permissions within the project

3. Create a JSON key for the service account

4. Create the configuration directory

install -d $configDir

1. Move the service account JSON key file to $configDir/credentials.json and then make it as private as possible:

chmod 600 $configDir/credentials.json

1. Share the calendar with the service account email address

2. Take note of the calendar ID

3. Save the calendar ID into the weekly tool by running weekly init and following its instructions to complete the configuration:

$HOME/go/bin/weekly init

Usage

Use weekly tutorial to understand how to format calendar events or read tutorial.md:

$HOME/go/bin/weekly tutorial

Use the weekly ls command to list calendar events:

$HOME/go/bin/weekly ls

Use:

$HOME/go/bin/weekly ls --help

or read lsexamples.txt to see additional weekly ls usage examples.

Use weekly --help to get interactive help:

$HOME/go/bin/weekly --help

Environment Variables

The weekly tool honors $XDG_CONFIG_HOME. If this variable is set, the config directory is:

$XDG_CONFIG_HOME/weekly

Otherwise, weekly uses this config directory:

$HOME/.config/weekly

Every command accepts the --config-dir <dir> flag to override the directory containing the configuration.

Files

The weekly tool requires two files inside its config directory:

1. credentials.json containing the service-account credentials and manually created during the first-time setup process.

2. calendar.json containing the ID of the calendar to use and created in the first-time setup process by weekly init.

Exit Code

The weekly tools exits with 0 on success and nonzero on failure.

Build From Source

You need Go >= 1.25. Run these commands:

git clone git@github.com/bassosimone/weekly
cd weekly
go build -v .

The ./weekly binary will be created in the current directory.

License

SPDX-License-Identifier: GPL-3.0-or-later

Direct Dependencies

• github.com/bassosimone/must
• github.com/bassosimone/runtimex
• github.com/bassosimone/vclip
• github.com/bassosimone/vflag
• github.com/google/go-cmp
• github.com/olekukonko/tablewriter
• github.com/rogpeppe/go-internal
• github.com/stretchr/testify
• golang.org/x/oauth2
• google.golang.org/api