# (Better) TimeTagger CLI
Track your time with [TimeTagger](https://timetagger.app/) from the command line.
TimeTagger is a (self-)hosted time tracking tool that helps you keep track of time spent on your tasks and projects.
This project provides a command-line interface (CLI) for the TimeTagger time tracking application, allowing you to manage your time entries directly from your terminal. It is a more feature-rich and ergonomic fork of the original [timetagger-cli](https://github.com/almarklein/timetagger_cli) by [Almar Klein](https://github.com/almarklein), adding a more user-friendly interface along with a number of new features, such as:
| | **better-timetagger-cli** | timetagger-cli |
| ----------------------------------- | :-----------------------: | :------------: |
| Start / stop tasks | ✅ | ✅ |
| Resume previous tasks | ✅ | ✅ |
| Display status update | ✅ | ✅ |
| List records by timeframe | ✅ | ✅ |
| Diagnose & fix database errors | ✅ | ✅ |
| Natural language support date/time | ✅ | ✅ |
| Easily tag records | ✅ | ❌ |
| Filter tasks by tags | ✅ | ❌ |
| Summary per tag | ✅ | ❌ |
| Hide / restore records | ✅ | ❌ |
| Export records to CSV | ✅ | ❌ |
| Import records from CSV | ✅ | ❌ |
| Preview records from CSV | ✅ | ❌ |
| Color-code output and render tables | ✅ | ❌ |
| Output rounded record times | ✅ | ❌ |
| Configurable date/time formats | ✅ | ❌ |
| Command aliases | ✅ | ❌ |
## 🚀 Quickstart
### 1. Install the `better-timetagger-cli` package.
```bash
$ pipx install better-timetagger-cli
```
### 2. Update the configuration with your `base_url` and `api_token`.
```bash
$ t setup
```
### 3. Review CLI commands and options.
```bash
$ t --help
# Usage: t [OPTIONS] COMMAND [ARGS]...
#
# Options:
# ...
#
# Commands:
# ...
$ t start --help
# Usage: t start [OPTIONS] [TAGS]...
#
# Options:
# ...
```
### 4. Manage your time with the command line interface.
```bash
$ t start client-a
# Started Stopped Duration Description
# ──────────────────────────────────────────────────────────────────────
# Tue 27-May-2025 08:15 ... 0m #client-a
$ t stop -a "in 15 minutes"
# Started Stopped Duration Description
# ──────────────────────────────────────────────────────────────────────
# Tue 27-May-2025 08:15 27-May-2025 08:30 15m #client-a
$ t show -s yesterday
# Started Stopped Duration Description
# ──────────────────────────────────────────────────────────────────────
# Tue 27-May-2025 08:15 27-May-2025 08:30 15m #client-a
# Mon 26-May-2025 13:20 26-May-2025 17:57 4h 37m #client-b
# Mon 26-May-2025 09:34 26-May-2025 12:40 3h 6m #client-b
$ t export -s "monday 8am" -e "friday 6pm" -o records.csv
# Exported 3 records to 'records.csv'.
```
## 📚 Documentation
For complete instructions, configuration details, and advanced features, visit the [full documentation on Read the Docs](https://better-timetagger-cli.readthedocs.io/).
## 🤝 Contributing
You are welcome to file **bug reports** and **feature requests** by opening a [github issue](https://github.com/PassionateBytes/better-timetagger-cli/issues) on this repository. If you’d like to contribute code, please consider starting with an issue to discuss the change before opening a pull request, to allow for a discussion of the intended change.
Pull requests (PRs) are appreciated and should reference a related bug report or feature request.
Raw data
{
"_id": null,
"home_page": null,
"name": "better-timetagger-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Paul B\u00fctof <paul@passionate-bytes.com>",
"keywords": "cli, command-line, productivity, self-hosted, self-hosting, time, time-tracking, timetagger, tracking",
"author": null,
"author_email": "Paul B\u00fctof <paul@passionate-bytes.com>",
"download_url": "https://files.pythonhosted.org/packages/16/6a/79d242d02ad7979307d46a0976d7753e26cc32bd42d607d8437947b0575b/better_timetagger_cli-0.6.1.tar.gz",
"platform": null,
"description": "# (Better) TimeTagger CLI\n\nTrack your time with [TimeTagger](https://timetagger.app/) from the command line.\n\nTimeTagger is a (self-)hosted time tracking tool that helps you keep track of time spent on your tasks and projects.\n\nThis project provides a command-line interface (CLI) for the TimeTagger time tracking application, allowing you to manage your time entries directly from your terminal. It is a more feature-rich and ergonomic fork of the original [timetagger-cli](https://github.com/almarklein/timetagger_cli) by [Almar Klein](https://github.com/almarklein), adding a more user-friendly interface along with a number of new features, such as:\n\n| | **better-timetagger-cli** | timetagger-cli |\n| ----------------------------------- | :-----------------------: | :------------: |\n| Start / stop tasks | \u2705 | \u2705 |\n| Resume previous tasks | \u2705 | \u2705 |\n| Display status update | \u2705 | \u2705 |\n| List records by timeframe | \u2705 | \u2705 |\n| Diagnose & fix database errors | \u2705 | \u2705 |\n| Natural language support date/time | \u2705 | \u2705 |\n| Easily tag records | \u2705 | \u274c |\n| Filter tasks by tags | \u2705 | \u274c |\n| Summary per tag | \u2705 | \u274c |\n| Hide / restore records | \u2705 | \u274c |\n| Export records to CSV | \u2705 | \u274c |\n| Import records from CSV | \u2705 | \u274c |\n| Preview records from CSV | \u2705 | \u274c |\n| Color-code output and render tables | \u2705 | \u274c |\n| Output rounded record times | \u2705 | \u274c |\n| Configurable date/time formats | \u2705 | \u274c |\n| Command aliases | \u2705 | \u274c |\n\n## \ud83d\ude80 Quickstart\n\n### 1. Install the `better-timetagger-cli` package.\n\n```bash\n$ pipx install better-timetagger-cli\n```\n\n### 2. Update the configuration with your `base_url` and `api_token`.\n\n```bash\n$ t setup\n```\n\n### 3. Review CLI commands and options.\n\n```bash\n$ t --help\n# Usage: t [OPTIONS] COMMAND [ARGS]...\n#\n# Options:\n# ...\n#\n# Commands:\n# ...\n\n$ t start --help\n# Usage: t start [OPTIONS] [TAGS]...\n#\n# Options:\n# ...\n```\n\n### 4. Manage your time with the command line interface.\n\n```bash\n\n$ t start client-a\n# Started Stopped Duration Description\n# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n# Tue 27-May-2025 08:15 ... 0m #client-a\n\n$ t stop -a \"in 15 minutes\"\n# Started Stopped Duration Description\n# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n# Tue 27-May-2025 08:15 27-May-2025 08:30 15m #client-a\n\n$ t show -s yesterday\n# Started Stopped Duration Description\n# \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n# Tue 27-May-2025 08:15 27-May-2025 08:30 15m #client-a\n# Mon 26-May-2025 13:20 26-May-2025 17:57 4h 37m #client-b\n# Mon 26-May-2025 09:34 26-May-2025 12:40 3h 6m #client-b\n\n$ t export -s \"monday 8am\" -e \"friday 6pm\" -o records.csv\n# Exported 3 records to 'records.csv'.\n```\n\n## \ud83d\udcda Documentation\n\nFor complete instructions, configuration details, and advanced features, visit the [full documentation on Read the Docs](https://better-timetagger-cli.readthedocs.io/).\n\n## \ud83e\udd1d Contributing\n\nYou are welcome to file **bug reports** and **feature requests** by opening a [github issue](https://github.com/PassionateBytes/better-timetagger-cli/issues) on this repository. If you\u2019d like to contribute code, please consider starting with an issue to discuss the change before opening a pull request, to allow for a discussion of the intended change.\n\nPull requests (PRs) are appreciated and should reference a related bug report or feature request.\n",
"bugtrack_url": null,
"license": null,
"summary": "A command line tool for TimeTagger. This is a more feature-rich and ergonomic fork of the original timetagger-cli (by Almar Klein), providing better user experience and additional features.",
"version": "0.6.1",
"project_urls": {
"Documentation": "https://better-timetagger-cli.readthedocs.io",
"Issues": "https://github.com/PassionateBytes/better-timetagger-cli/issues",
"Repository": "https://github.com/PassionateBytes/better-timetagger-cli"
},
"split_keywords": [
"cli",
" command-line",
" productivity",
" self-hosted",
" self-hosting",
" time",
" time-tracking",
" timetagger",
" tracking"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "718bc6d8dcaaf6eb96402c1f744e7561eeb2de80fddb11fb051b79e979341dd8",
"md5": "8e2fac2aaa90b79672b3a3d14cc4cb69",
"sha256": "6a2e5a4f0cfc2fa0818f59fe9386b98d095639503af112a8589de3f93e6cf427"
},
"downloads": -1,
"filename": "better_timetagger_cli-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8e2fac2aaa90b79672b3a3d14cc4cb69",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 38357,
"upload_time": "2025-10-16T17:17:20",
"upload_time_iso_8601": "2025-10-16T17:17:20.008868Z",
"url": "https://files.pythonhosted.org/packages/71/8b/c6d8dcaaf6eb96402c1f744e7561eeb2de80fddb11fb051b79e979341dd8/better_timetagger_cli-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "166a79d242d02ad7979307d46a0976d7753e26cc32bd42d607d8437947b0575b",
"md5": "eb83d2c3866a54335f1dc1872f6abdbc",
"sha256": "0d516bb4feec60e220d00c81b9df6b77031df6a82a257d32efa1b11b6784e812"
},
"downloads": -1,
"filename": "better_timetagger_cli-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "eb83d2c3866a54335f1dc1872f6abdbc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 147345,
"upload_time": "2025-10-16T17:17:21",
"upload_time_iso_8601": "2025-10-16T17:17:21.395990Z",
"url": "https://files.pythonhosted.org/packages/16/6a/79d242d02ad7979307d46a0976d7753e26cc32bd42d607d8437947b0575b/better_timetagger_cli-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-16 17:17:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PassionateBytes",
"github_project": "better-timetagger-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "better-timetagger-cli"
}
JSON
