Tracker CLI

A robust, extensible Node.js command-line tool for tracking time spent on tasks and tickets. Designed for developers, freelancers, and teams who need accurate time auditing, reporting, phase tracking, metadata management, and multitasking breakdowns.

Table of Contents

• Features
• Installation
• Quick Start
• Commands
  • start
  • stop
  • status
  • report
  • delete
  • audit
  • amend
  • switch-phase
  • delete-event
  • ls
  • create-ticket
  • describe
• Advanced Reporting
• Database Schema
• Code Structure
• Extending Tracker
• Troubleshooting
• Contributing
• License
• Repository
• Authors & Credits
• Acknowledgements
• Contact

Features

• Start/Stop Ticket Tracking: Log time against tickets/tasks with optional descriptions and phases.
• Ticket Metadata: Create tickets with metadata including tags, due dates, project, priority, and timestamps.
• Status: View currently active tickets, their phase, and start times.
• Advanced Reporting: Multi-ticket reports, windows, sorting, filtering, phase breakdowns, multitasking, and work-hour calculation.
• Ticket Inspection: Describe full ticket metadata using describe.
• Interactive Editing: Edit descriptions, amend events, switch phases, and create tickets interactively.
• Multitasking Analysis: Detect overlapping work intervals.
• Event Safety: Delete events safely with full sequence simulation.
• Extensible: Modular command structure for easy feature additions.

Installation

Prerequisites

• Node.js (v16+ recommended)
• npm (v7+)

Install Dependencies

npm install

(Optional) Link CLI Globally

npm link

Quick Start

1. Start Tracking a Ticket

tracker start TICKET-123 "Fix login bug" --phase Coding
# Or use shortcuts:
tracker start TICKET-123 "Fix login bug" -p Coding
# Or skip phase selection entirely:
tracker start TICKET-123 "Fix login bug" --skip-phase

2. Stop Tracking

tracker stop TICKET-123

3. View Status

tracker status

4. Generate a Report

tracker report --sort time_spent --order DESC --multitask

Commands

start

Start tracking time for a ticket. Creates the ticket if it doesn't exist.

tracker start <ticket> [description] [-p, --phase <phase>] [-sp, --skip-phase]

stop

Stop tracking time for a ticket or all tickets.

tracker stop <ticket>
tracker stop --all

status

Show all active tickets.

tracker status

report

Generate a detailed report of time spent across tickets, with support for filtering, sorting, windows, and phase/time analysis.

tracker report [tickets...] [options]

Options:

• --start, -s <datetime> — Start of time window
• --end, -e <datetime> — End of time window
• --project <names> — Filter by project (comma-separated)
• --tag, -t <tags> — Filter by tag (comma-separated)
• --phase <phases> — Only count time spent in specific phases
• --sort <field> — One of: ticket, time_spent, active_since, first_started, last_stopped
• --order <ASC|DESC> — Sort direction
• --multitask, -m — Show multitasking analysis
• --calculate_work_hours, -cwh — Count total non-overlapping work hours

Examples:

tracker report --sort time_spent --order DESC
tracker report TKT-1 TKT-2
tracker report --project Platform
tracker report --tag backend,urgent
tracker report --phase Design
tracker report --start 2025-10-01T00:00:00 --end 2025-10-31T23:59:59

delete

Delete tickets and all associated events.

tracker delete [tickets...]

Options:

• --all — Delete all tickets
• --tag <tag> — Delete tickets by tag
• --project <project> — Delete tickets by project

Examples:

tracker delete TKT-1 TKT-2
tracker delete --project MobileApp
tracker delete --tag urgent
tracker delete --all

audit

Show audit history for a ticket.

tracker audit <ticket>

amend

Amend event fields interactively or via arguments.

tracker amend <eventId> [action] [datetime] [--phase <phase>]

switch-phase

Switch the phase of a ticket.

tracker switch-phase <ticket> <phase>

delete-event

Delete one or multiple events safely.

tracker delete-event <eventId...>

ls

List all tickets, including metadata.

tracker ls

create-ticket

Create a ticket with metadata. Missing fields are prompted interactively.

tracker create-ticket <name> [--description <text>] [--tags <csv>] [--due <date>] [--project <name>] [--priority <level>]

describe

Display metadata for one or more tickets.

tracker describe [tickets...] [--fields <columns>] [--all]

Advanced Reporting

Tracker supports advanced analytics including:

• Multi-ticket reporting
• Project, tag, and phase filtering
• Custom time windows
• Sorting by time, activity, or timestamps
• Phase breakdowns per ticket or across selected tickets
• Multitasking detection
• Accurate non-overlapping work-hour computation

Database Schema

Metadata columns added in 0.6.0:

• tags
• dueDate
• project
• priority
• createdAt
• updatedAt

Schema remains backward compatible via migrations.

Code Structure

• src/commands/ — All CLI commands
• src/db.js — SQLite management

Extending Tracker

Tracker supports adding new commands, schema fields, and features.

Troubleshooting

SQLite Concurrency Limitations

Issue: When running multiple tracker commands simultaneously (e.g., creating many tickets in parallel), some operations may fail with "database is locked" errors.

Cause: SQLite only supports one writer at a time. Commands like:

# This may cause some tickets to fail
for i in {1..20}; do tracker start $i "ticket $i" -sp & done

Workarounds:

• Run commands sequentially instead of in parallel
• Add a small delay between commands: sleep 0.1
• Use the serial approach:

# This works reliably
for i in {1..20}; do tracker start $i "ticket $i" -sp; done

Future:

• No fix planned for local database users
• There exists a plan to implement remote (centralized) database logging
  • This central database would implement true database systems thereby solving the concurrency issues of the current local system

Other Issues

• Missing config or DB issues
• Inconsistent event sequences during deletes
• Multi-ticket or filter conflicts in reports

Contributing

Fork, branch, PR.

License

See LICENSE file.

Repository

Coming soon.

Authors & Credits

• Author: ByteHawk

Acknowledgements

• Commander.js
• sqlite3
• chalk
• inquirer

Contact

Feature requests or issues can be opened after v1.0.0.