timedctl-rs

DISCLAIMER: This project was to a majority generated by AI and should not be used for production purposes without serious code review.

A Rust implementation of the timedctl CLI and libtimed library for interacting with the Timed time tracking system.

Overview

This project is a Rust rewrite of the Python-based timedctl and libtimed. It provides:

1. A library crate (libtimed-rs) for Timed API interaction
2. A binary crate (timedctl-rs) for CLI-based time tracking

Supported Timed Features

• 🔐 OIDC Device Flow Authentication
• ⏱️ Activity Tracking
• 📝 Report Manglement

Installation

Using Cargo

cargo install timedctl-rs

Manually

git clone https://github.com/cfi2017/timedctl-rs.git
cd timedctl-rs
cargo build --release

The binary will be available at ./target/release/timedctl.

From Releases

You can download pre-built binaries for various platforms from the GitHub Releases page.

Usage

Configuration

On first run, timedctl-rs will create a configuration file at $XDG_CONFIG_HOME/timedctl/config.toml (Linux/macOS) or %APPDATA%\timedctl\config.toml (Windows).

You can manage your configuration using the built-in commands:

# Get started with a new configuration
timedctl config init

# View your configuration file location
timedctl config path

# Configure your settings (these commands work even if no config exists yet)
timedctl config set username "your-username"
timedctl config set timed_url "https://your-timed-instance.example.com"
timedctl config set sso_discovery_url "https://your-sso.example.com"
timedctl config set sso_client_id "your-client-id"

# View current configuration
timedctl config view

# Reset configuration to defaults if needed
timedctl config reset

Required configuration:

• Username
• Timed API URL
• SSO discovery URL
• SSO client ID

Basic Commands

# Get current overtime
timedctl get overtime

# Start an activity
timedctl activity start "Working on project X" --project "Project X" --task "Development"

# Stop the current activity
timedctl activity stop

# Add a time report
timedctl add report --customer "Customer" --project "Project" --task "Task" --duration "1:30" --description "Description"

# Add a time report for a specific date
timedctl add report --customer "Customer" --project "Project" --task "Task" --duration "1:30" --description "Description" --date "2023-07-15"

# View today's activities (for the current user by default)
timedctl get activities

# View activities for a specific date
timedctl get activities --date 2023-07-15

# View activities for a date range
timedctl get activities --from 2023-07-01 --to 2023-07-31

# View currently active activity
timedctl activity show

# View activities for all users
timedctl get activities --all-users

# Manage configuration (commands can be run in any order)
timedctl config set username "your-username"
timedctl config set timed_url "https://timed.example.com"
timedctl config view

# View/edit reports and activities
timedctl get reports                  # Current user's reports for today
timedctl get reports --all-users      # All users' reports for today
timedctl delete report --date 2023-07-15  # Delete one of your reports
timedctl activity show                # Show current active activity details
timedctl activity show --short        # Show just the activity comment

Development

Building

cargo build

Running Tests

cargo test

Linting and Formatting

# Run clippy for linting
cargo clippy

# Format code
cargo fmt

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality. To use them:

1. Install pre-commit: pre-commit.com
2. Set up the git hooks: pre-commit install

The pre-commit hooks will automatically:

• Format Rust code with cargo fmt
• Run linting with cargo clippy
• Fix trailing whitespace and file endings

CI/CD Pipeline

This project uses GitHub Actions for continuous integration and deployment:

• CI Workflow: Runs on every push and pull request to the main branch, performing:

  • Code formatting checks
  • Linting with Clippy
  • Building the project
  • Running tests
  • Cross-platform builds (Linux, macOS, Windows)

• Release Workflow: Automatically creates new releases when changes are merged to main:

  • Uses go-semantic-release for version management based on conventional commits
  • Uses GoReleaser for building and releasing binaries
  • Builds binaries for multiple platforms (Linux, macOS, Windows)
  • Attaches binaries to GitHub releases
  • Generates release notes based on commits since the last tag

Contributing

Please see CONTRIBUTING.md for guidelines on how to contribute to this project.

Migration Status

See MIGRATION_STATUS.md for the current status of the migration from Python to Rust.

License

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

Releases

Releases are managed automatically using go-semantic-release and GoReleaser with GitHub Actions. When code is merged to the main branch, a new release is created if needed based on conventional commit messages:

• feat: commits trigger a minor version bump
• fix: commits trigger a patch version bump
• feat!: or fix!: commits with breaking changes trigger a major version bump

The release notes are generated automatically based on the commit messages since the last tag. The configuration for go-semantic-release is stored in the .gsr.yaml file and GoReleaser configuration is in .goreleaser.yaml at the root of the project.