toggl-to-sqlite

Save data from Toggl to a SQLite database using the modern Toggl API v9.

Features

• ✅ Toggl API v9 - Uses the latest Toggl API for maximum compatibility
• ✅ Complete Data Export - Time entries, workspaces, and projects
• ✅ Flexible Date Ranges - Fetch all data or specify custom date ranges
• ✅ SQLite Storage - Portable, queryable database format
• ✅ 100% Test Coverage - Reliable and well-tested codebase
• ✅ Modern Python - Supports Python 3.9+
• ✅ Modern Tooling - Built with uv, ruff, and automated versioning

How to install

With uv (recommended)

$ uv add toggl-to-sqlite

With pip

$ pip install toggl-to-sqlite

Usage

You will need to first obtain a valid API token for your toggl account. You can do this by running the auth command and following the prompts:

$ toggl-to-sqlite auth
You will need to get your API Token from this page

https://track.toggl.com/profile

Once you have your API Token enter it at the command line.

Authentication tokens written to auth.json

Now you can fetch all of your items from toggl like this:

$ toggl-to-sqlite fetch toggl.db

NB! By default toggl-to-sqlite only fetches data from the 25 previous days. As an alternative you can specify to get time_entries since a specific date. You do this by specifying the since option:

$ toggl-to-sqlite fetch -s 2021-03-13

You can choose to get only time_entries, projects, or workspaces by speciying a type in the argument like this.

To get ONLY your workspaces:

$ toggl-to-sqlite fetch -t workspaces toggl.db

To get your workspaces and projects:

$ toggl-to-sqlite fetch -t workspaces -t projects toggl.db

The default is to get all three of time_entries, projects, and workspaces

toggl-to-sqlite --help

Usage: toggl-to-sqlite [OPTIONS] COMMAND [ARGS]...

  Save Toggl data to a SQLite database

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  auth   Save authentication credentials to a JSON file
  fetch  Save Toggl data to a SQLite database

Using with Datasette

The SQLite database produced by this tool is designed to be browsed using Datasette. Use the datasette-render-timestamps plugin to improve the display of the timestamp values.

Development

This project uses modern Python tooling for development.

Prerequisites

• Python 3.9+
• uv (recommended) or pip

Setup with uv (recommended)

git clone https://github.com/ryancheley/toggl-to-sqlite
cd toggl-to-sqlite
uv sync --extra test

Setup with pip

git clone https://github.com/ryancheley/toggl-to-sqlite
cd toggl-to-sqlite
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[test]"

Running tests

# With uv
uv run pytest

# With pip
pytest

Code quality

This project uses ruff for linting and formatting:

# With uv
uv run ruff check .          # Linting
uv run ruff format .         # Formatting

# With pip
ruff check .
ruff format .

Version management

Versions are automatically managed using git tags:

# Create a new version
git tag v0.9.0
git push origin v0.9.0

# Or use the bump script
python bump-version.py patch  # 0.8.2 -> 0.8.3
python bump-version.py minor  # 0.8.2 -> 0.9.0
python bump-version.py major  # 0.8.2 -> 1.0.0

See CONTRIBUTING.md for more information on contributing to this project.

Requirements

• Python 3.9 or higher
• Valid Toggl account with API access