Timesheetz is a timesheet management application with two interfaces:
- Terminal User Interface (TUI): Add, view, and delete timesheet entries directly from your terminal.
- REST API: Programmatically manage timesheet entries through HTTP endpoints. Supports the same operations as the TUI.
The application stores all entries in a Sqlite database and features:
- 📅 Monthly calendar view with weekend indicators
- 📋 Copy/paste functionality with visual feedback
- 📊 Automatic total calculations
- 📤 Export to PDF or Excel
- 📧 Email integration via Resend.com
- 🔄 Real-time updates via API
- ⌨️ Vim-inspired keyboard shortcuts
- 🔄 Automatic startup on system boot
- 🛠️ Easy management with control scripts
- Download the latest release from the releases page
- Extract the archive
- Run the installation script:
cd timesheetz chmod +x scripts/install.sh ./scripts/install.sh
- Download the appropriate binary for your system from the releases page
- Make the binary executable:
chmod +x timesheet-<os>-<arch>
- Move the binary to a directory in your PATH:
mv timesheet-<os>-<arch> ~/.local/bin/timesheet
-
Clone the repository:
git clone https://github.com/joelgrimberg/timesheetz.git cd timesheetz -
Build the project:
./scripts/build.sh
-
Install the Launch Agent (macOS):
./scripts/install.sh
The installation script will:
- Create a Launch Agent in
~/Library/LaunchAgents - Configure Timesheetz to start at login and run in the background
- Write logs to
~/Library/Logs/timesheetz.outand~/Library/Logs/timesheetz.err
To verify or manage the Launch Agent:
- Check if it's running:
launchctl list | grep timesheetz - Stop auto-starting:
launchctl unload ~/Library/LaunchAgents/com.timesheetz.plist - Remove the Launch Agent:
rm ~/Library/LaunchAgents/com.timesheetz.plist
When the Launch Agent is running (on port 8080), you can start additional instances of Timesheetz from the CLI:
-
For a terminal UI instance, use a different port:
./bin/timesheet --port 8081
-
For a background instance, use the
--no-tuiflag:./bin/timesheet --no-tui --port 8082
All instances will share the same database, allowing you to:
- Have the app running in the background via Launch Agent
- Use the terminal UI for quick entries or queries
- Run multiple background instances if needed
Note: If you get a port binding error, it means the port is already in use. Try using a different port number.
After installation, you can run Timesheet using the following command:
timesheetFor more options, run:
timesheet --helpThe application comes with a management script that provides easy control over the application lifecycle:
# Check application status
./scripts/manage.sh status
# Stop the application
./scripts/manage.sh stop
# Start the application
./scripts/manage.sh start
# Restart the application
./scripts/manage.sh restart
# Reload the application (graceful reload)
./scripts/manage.sh reloadTo update to a newer version:
-
Stop the current version:
./scripts/manage.sh stop
-
Build and install the new version:
./scripts/build.sh ./scripts/install-mac.ps1 or install-win.ps1 or install-linux.sh
-
Start the new version:
./scripts/manage.sh start
Or simply use the restart command:
./scripts/manage.sh restartRun the application in dev mode as a TUI with the following command:
make devRun the application as a background service with the --no-tui flag:
make dev ARGS="--no-tui"The application supports the following command-line flags:
--no-tui: Run only the API server without the TUI--tui-only: Run only the TUI without the API server--add: Add a new entry for today and exit--port <number>: Specify the port for the API server (default: 8080)--dev: Run in development mode (uses local database)--init: Initialize the database--help: Show help message--verbose: Show detailed output
Example:
# Run API server on port 3000 in development mode
./timesheet --no-tui --port 3000 --dev
# Run only the TUI without the API server
./timesheet --tui-only
# Add a new entry for today and exit
./timesheet --add
# Show help message
./timesheet --helpThe application uses keyboard shortcuts for navigation and actions. See the keyboard shortcuts guide for a comprehensive list of available commands.
The application can be configured through config.json:
- Set document type (PDF/Excel) for exports
- Configure email settings (requires Resend.com API key)
- Enable/disable API server
- Set development mode to avoid cluttering production data
Within the config file, make sure to set mode to "development" to not clutter your production data.
Log files can be found in the following locations:
- macOS:
$HOME/Applications/Timesheetz/error.logandoutput.log - Windows:
%LOCALAPPDATA%\Timesheetz\ - Linux: Use
journalctl --user -u timesheetz.service
The application provides a REST API for programmatic access. See the API documentation for available endpoints and examples.
The training budget API provides endpoints for managing training budget entries and retrieving training hours.
-
Get Training Budget Entries
GET /api/training-budget?year=2024
Returns all training budget entries for the specified year.
-
Create Training Budget Entry
POST /api/training-budget Content-Type: application/json { "date": "2024-03-15", "training_name": "API Test Training", "hours": 8, "cost_without_vat": 1000.00 }
Creates a new training budget entry.
-
Update Training Budget Entry
PUT /api/training-budget Content-Type: application/json { "id": 1, "date": "2024-03-15", "training_name": "Updated API Test Training", "hours": 16, "cost_without_vat": 2000.00 }
Updates an existing training budget entry.
-
Delete Training Budget Entry
DELETE /api/training-budget?id=1
Deletes a training budget entry by ID.
-
Get Total Training Hours
GET /api/training-hours?year=2024
Returns the total training hours for the specified year.
# Get all training budget entries for 2024
curl -X GET "http://localhost:8080/api/training-budget?year=2024"
# Create a new training budget entry
curl -X POST "http://localhost:8080/api/training-budget" \
-H "Content-Type: application/json" \
-d '{
"date": "2024-03-15",
"training_name": "API Test Training",
"hours": 8,
"cost_without_vat": 1000.00
}'
# Get total training hours for 2024
curl -X GET "http://localhost:8080/api/training-hours?year=2024"-
update Readme and setup github pages
-
Build application in pipeline
-
Add RayCast extension
-
Training Budget View Enhancements:
- Press
cwhile hovering a row to clear (delete) the selected training budget entry. - The view refreshes automatically after deletion.
- Press
-
Database Improvements:
- The
training_budgettable is now created automatically in new/clean setups. - Existing databases can be updated manually without affecting current data.
- The