README.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# 👊 Punchcard ♦️

A simple time tracking CLI tool for freelancers and consultants.

## What it does

Punchcard helps you track your work hours and generate professional invoices and timesheets. Start and stop timers from the command line, then generate PDF reports when you're ready to bill your clients.

## Quick Start

```bash
# Set your own info
punch set name="John Doe" label="Web Design" email="john@doe.com"

# Set up a client and a project
punch add client AcmeCorp bossman@acmecorp.com --hourly-rate 120
punch add project -c AcmeCorp 'Website Redesign'

# Start tracking time
punch in -c AcmeCorp

# Stop tracking time  
punch out

# Check current status
punch status

# Generate reports
punch report unified -c AcmeCorp -d 'last month'
punch report timesheet -c AcmeCorp -d 'this week'
```

## Commands

### Time Tracking
- `punch in` - Start a timer for the current work session
- `punch out` - Stop the active timer
- `punch status` - Show current timer status and recent time entries

### Data Management
- `punch add client <name>` - Add a new client to the database
- `punch add project <name>` - Add a new project to the database
- `punch import <file>` - Import time data from CSV files (supports Clockify CSV exports)

### Reports
- `punch report invoice` - Generate a PDF invoice from tracked time
- `punch report timesheet` - Generate a PDF timesheet report
- `punch report unified` - Generate a PDF containing an invoice followed by a timesheet

## Full TUI

```bash
punch tui  # or just `punch`
```

![screenshot of the punch TUI](tui-screenshot.jpg)

## How it works

When you run `punch in`, a timer starts recording to a local SQLite database. Run `punch out` to stop the timer. Your time data stays on your machine - nothing is sent to external servers.

Reports are generated using Typst and compiled to PDF automatically.

## Installation

If you have Go installed:
```bash
go install git.tjp.lol/punchcard/cmd/punch@latest
```

Or build from source:
```bash
git clone https://git.tjp.lol/punchcard.git
cd punchcard
go install ./cmd/punch
```

## Requirements

- Go 1.21+ (for building from source)
- Typst (for PDF generation)