Homer 🏠

Homer is a personal productivity CLI for developers — Jira and Clockify integrations from your terminal.

Documentation

• INSTALL.md — Installation, credentials, and configuration
• USAGE.md — Full feature guide and workflows
• CHEATSHEET.md — Quick command reference
• TROUBLESHOOTING.md — Common issues and solutions

Features

⏱️ Clockify Time Tracking

• Start/stop timers with description, project, and tags
• Interactive selectors for projects (from Clockify + Jira) and tags
• View the currently running timer with elapsed time
• Summary and detailed reports by date range, project, or tag

🎯 Jira Issue Management

• List your open issues
• View issue details (status, priority, assignee, description)
• Create issues with type, priority, and description
• Comment on issues and mention teammates

Installation

pipx install homer-cli   # recommended
homer init               # interactive credential setup

See INSTALL.md for detailed instructions.

Quick Start

homer init                                  # configure credentials

homer jira list                             # see your open issues
homer jira view NDI-123                     # view issue details

homer ck start "Fixing login bug"           # start a timer
homer ck start "Code review" -p "web-api"   # with project
homer ck start "Standup" -T                 # open tag selector
homer ck current                            # check elapsed time
homer ck stop                               # stop all timers

homer ck summary 2026-01-01 2026-01-31      # monthly report

Commands Reference

Both homer clockify and homer ck are equivalent.

Global

Clockify — Timers

start options:

Clockify — Reports

Dates use YYYY-MM-DD format.

Jira

create options:

Configuration

Homer reads credentials from ~/.env:

JIRA_BASE_URL=https://company.atlassian.net
JIRA_USER=you@company.com
JIRA_API_TOKEN=your_token

CLOCKIFY_API_KEY=your_api_key
CLOCKIFY_WORKSPACE=workspace_id
CLOCKIFY_USER=alphanumeric_user_id

⚠️ CLOCKIFY_USER must be the alphanumeric ID (e.g. 646b733087e7196c5c918748), not your email.
Get it with: curl -H "X-Api-Key: YOUR_KEY" https://api.clockify.me/api/v1/user | grep '"id"'

Run homer init to set or update credentials interactively.

Project Structure

src/homer/
├── cli.py            # Root CLI (registers clockify, ck, jira)
├── config.py         # Settings from ~/.env
├── exceptions.py     # Error types
├── clockify/
│   ├── client.py     # HTTP client (httpx)
│   ├── service.py    # Business logic
│   ├── commands.py   # CLI commands (Typer + Rich)
│   └── models.py     # Pydantic models
└── jira/
    ├── client.py
    ├── service.py
    ├── commands.py
    └── models.py
tests/                # pytest test suite

Development

git clone https://github.com/marcelohfonseca/homer-cli.git
cd homer && pdm install

pdm run pytest tests/          # run tests
pdm run ruff check src/        # lint
pdm run mypy src/               # type check
pdm run homer --help            # run from source

License

MIT — see LICENSE file.