Crate tempo_cli

Expand description

§Tempo

Simple, Fast, and Privacy-Focused Time Tracking for Developers

Tempo is a lightweight, terminal-based time tracking tool designed specifically for developers. It automatically detects your project context, tracks time with precision, and stores everything locally. No cloud services, no subscriptions, just a fast binary that gets out of your way.

§🚀 Why Tempo?

Zero Friction: Start tracking in seconds. Tempo infers your project from your current directory.
Local & Private: Your data lives on your machine in a standard SQLite database. You own it.
Resource Efficient: The background daemon is written in Rust, consuming negligible CPU and memory (< 5MB).
Developer Native: Integrates with your existing workflow. Detects Git, Node, Rust, Python, and Go projects automatically.
Terminal First: Includes a beautiful TUI dashboard and interactive timer for those who live in the terminal.

§✨ Features

§🧠 Smart Context Detection

Tempo automatically recognizes project roots by looking for common markers:

.git/
package.json
Cargo.toml
pyproject.toml / requirements.txt
go.mod
pom.xml

§⏱️ Intelligent Session Management

Auto-Resume: Pick up exactly where you left off.
Idle Detection: Automatically pauses tracking when you step away (configurable).
Concurrent Projects: Switch contexts instantly without losing data.

§📊 Powerful Reporting

Generate detailed reports to analyze your productivity or for billing purposes:

Formats: ASCII tables, CSV, JSON.
Filters: Date ranges, specific projects, or tags.
Aggregation: View daily, weekly, or project-based totals.

§🖥️ Interactive Dashboard

A full-featured Terminal User Interface (TUI) offering:

Real-time status monitoring.
Visual project switcher.
Activity timeline and statistics.
Keyboard-driven navigation.

§🏗️ Architecture

Tempo follows a Client-Daemon architecture to ensure reliability and speed.

graph LR
    CLI[Tempo CLI] -- Unix Socket --> Daemon[Tempo Daemon]
    Daemon -- Reads/Writes --> DB[(SQLite DB)]
    Daemon -- Monitors --> System[System Activity]

CLI: A thin client that sends commands to the daemon. It exits immediately, keeping your shell responsive.
Daemon: A background process that manages state, handles database I/O, and monitors system idle time. It ensures time is tracked accurately even if you close your terminal.
Storage: All data is persisted in a local SQLite database at ~/.tempo/data.db.

§📥 Installation

§Option 1: Python Package (Recommended)

The easiest way to install Tempo is via pip or uv. The Python package automatically installs the Rust binary for your platform.

# Fast installation with uv
uv add tempo-tracker-cli

# Or using standard pip
pip install tempo-tracker-cli

§Option 2: Rust / Cargo

If you have a Rust toolchain installed, you can install directly from crates.io or build from source.

# Install from crates.io
cargo install tempo-cli

# Or build from source
git clone https://github.com/own-path/tempo.git
cd tempo
cargo build --release
cargo install --path .

§Package Information

Tempo is distributed as two packages:

Python Package: tempo-tracker-cli - Provides easy installation and automatically manages the Rust binary
Rust Package: tempo-cli - The core application binary

Both packages install the same tempo command-line tool. Choose Python for convenience or Rust for building from source.

§System Requirements

OS: macOS, Linux, or Windows (WSL recommended)
Terminal: A terminal with TrueColor support (e.g., iTerm2, Alacritty, Ghostty) and a Nerd Font installed is recommended for the best TUI experience

§⚡ Quick Start

Start the Daemon
```
tempo start
```
Initialize a Project Navigate to your project folder and tell Tempo to track it.
```
cd ~/my-cool-project
tempo init "My Cool Project"
```
Start Tracking
```
tempo session start
```
Tempo will confirm that tracking has started for “My Cool Project”.
Check Status
```
tempo status
```
View the Dashboard
```
tempo dashboard
```

§📖 Usage Guide

§Session Management

Command	Description
`tempo session start`	Start tracking time for the current project.
`tempo session stop`	Stop the current session.
`tempo session pause`	Pause the current session (useful for breaks).
`tempo session resume`	Resume a paused session.
`tempo session current`	Display details of the active session.
`tempo session list`	Show a history of recent sessions.
`tempo session edit <id>`	Modify a past session (e.g., fix start/end times).
`tempo session delete <id>`	Permanently remove a session.

§Project Management

Command	Description
`tempo init "<Name>"`	Initialize tracking for the current directory.
`tempo list`	List all tracked projects.
`tempo project archive <id>`	Archive a project (hides it from default lists).
`tempo project update-path`	Update the path if you moved the project folder.

§Reporting

Generate reports to visualize your time usage.

# Standard ASCII report
tempo report

# Export to CSV for Excel/Numbers
tempo report --format csv > timesheet.csv

# Filter by date
tempo report --from 2024-01-01 --to 2024-01-31

# Filter by project
tempo report --project "My Cool Project"

§Interactive UI

tempo dashboard: The main command center. View active sessions, switch projects, and see daily stats.
tempo timer: A focused, full-screen timer view. Great for keeping on a secondary monitor.
tempo history: An interactive browser for your session history.

§⚙️ Configuration

Tempo is highly configurable. Settings are stored in ~/.tempo/config.toml.

You can view and modify settings via the CLI:

# View current config
tempo config show

# Set a value
tempo config set idle_timeout_minutes 10

§Available Options

Key	Type	Default	Description
`idle_timeout_minutes`	Number	`30`	Minutes of inactivity before auto-pausing.
`auto_pause_enabled`	Boolean	`true`	Whether to enable auto-pause functionality.
`default_context`	String	`"terminal"`	Default tag for sessions (`terminal`, `ide`, `manual`).
`max_session_hours`	Number	`48`	Safety limit to auto-stop extremely long sessions.
`backup_enabled`	Boolean	`true`	Enable automatic database backups.
`log_level`	String	`"info"`	Log verbosity (`error`, `warn`, `info`, `debug`).

§🔧 Troubleshooting

§Daemon Not Starting

If tempo start fails, check if a stale PID file exists:

rm ~/.tempo/daemon.pid
tempo start

§“Connection Refused”

This usually means the daemon isn’t running. Start it with:

tempo start

§Missing Icons in TUI

If you see boxes [] or ? instead of icons, ensure you are using a Nerd Font in your terminal emulator.

§🤝 Contributing

We welcome contributions! Whether it’s bug reports, feature requests, or code, your help is appreciated.

Fork the repository.
Create a feature branch (git checkout -b feature/amazing-feature).
Commit your changes.
Push to the branch.
Open a Pull Request.

See CONTRIBUTING.md for detailed guidelines.

§Release Process

Releases are fully automated via release-plz:

Version Management: Automated PRs are created for version bumps based on conventional commits
Dual Publishing: Merging to main triggers simultaneous publication to both crates.io and PyPI
Synchronized Versions: Both packages maintain version parity automatically

§📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

_{Built with ❤️ by Developers, for Developers.}

Re-exports§

pub use db::*;
pub use models::*;
pub use utils::*;

Modules§

cli
db
models
services
test_utils
ui
utils

Crate tempo_cli

Crate tempo_cli Copy item path

§Tempo

§📖 Table of Contents

§🚀 Why Tempo?

§✨ Features

§🧠 Smart Context Detection

§⏱️ Intelligent Session Management

§📊 Powerful Reporting

§🖥️ Interactive Dashboard

§🏗️ Architecture

§📥 Installation

§Option 1: Python Package (Recommended)

§Option 2: Rust / Cargo

§Package Information

§System Requirements

§⚡ Quick Start

§📖 Usage Guide

§Session Management

§Project Management

§Reporting

§Interactive UI

§⚙️ Configuration

§Available Options

§🔧 Troubleshooting

§Daemon Not Starting

§“Connection Refused”

§Missing Icons in TUI

§🤝 Contributing

§Release Process

§📄 License

Re-exports§

Modules§

Crate tempo_cli