DEV Community: Cris Mihalache

Productivity Perfected: How I Wrapped Up the Super Time Tracker UI

Cris Mihalache — Fri, 29 May 2026 02:32:54 +0000

This is a submission for the GitHub Finish-Up-A-Thon Challenge

What I Built

Hey there! I'm thrilled to share what I've been working on: the "Super Time Tracker UI." It's a Next.js application designed to make tracking your time not just efficient, but genuinely helpful for boosting your productivity. I poured a lot of effort into making it intuitive and powerful, leveraging modern web tech for a really smooth experience.

Here’s a peek at what it can do:

Time Tracking: Effortlessly check in and out of tasks, with easy ways to edit and manage all your entries.
Tagging and Organization: Keep everything organized with tags, making it simple to search and analyze your time.
Detailed Reporting: Dive deep into your productivity with comprehensive reports and analytics based on your tracked time.
User Authentication: A secure system to get you started and keep your data safe.
Customizable Settings: Personalize everything from display preferences and data management (like backup/restore and export) to focus goals, notifications, and even a Pomodoro timer.
Cloud Synchronization: Built-in cloud integration means your data is always there, across all your devices, and safely backed up.
Command Palette: Need to do something fast? Our central command palette gives you quick access to just about everything.
Pomodoro Timer: A handy built-in Pomodoro timer to help you stay focused and manage your work breaks.
Notes and Templates: Add detailed notes to your entries and create reusable templates for those tasks you do all the time.
Offline Support: Life happens! You can still track your time even when you're not connected to the internet.

Under the hood, the app has dedicated API routes for all its data magic (app/api), a rich collection of beautiful, reusable UI components (components), and a solid library of utility functions (lib) that handle everything from data crunching to making sure your UI preferences are just right.

Demo

npm
Github

The Comeback Story

This project's journey, especially during the GitHub Finish-Up-A-Thon Challenge, has been incredibly rewarding. The "Super Time Tracker UI" had a really strong foundation, but it needed that extra push—that final polish and those crucial features—to truly feel complete.

My main focus for this "comeback" was on:

Making it Feel Great to Use: I spent a lot of time improving existing UI components like entry-list-item.tsx, check-in-form.tsx, and active-entry-panel.tsx. The goal was to make them more intuitive, responsive, and visually appealing, ensuring a consistent and delightful experience throughout the app.
Smarter Data Management: The cloud synchronization feature (cloud-sync-provider.tsx, cloud-sync-settings-view.tsx) got a major overhaul to make it even more reliable and speedy. I also built out robust backup and restore functionalities (backup-restore-setting.tsx), plus comprehensive data export options (build_csv_export.ts, build_json_export.ts, build_markdown_export.ts) so you have complete control over your data.
Brand New Productivity Tools: I added a bunch of new features designed to supercharge your productivity. This included expanding the reporting capabilities in reporting/page.tsx with even more detailed analytics, implementing a clever notification-rules-runner.tsx for customizable reminders, and making the Pomodoro timer in pomodoro-view.tsx even more integrated and useful.
Boosting Performance and Stability: A big chunk of effort went into finding and fixing anything that slowed things down, especially in areas with lots of data like entry-list.tsx and reporting/page.tsx. I squashed a lot of bugs and made stability improvements across the board, all to ensure a smooth and reliable experience.
Clean Code for the Future: I also focused on the overall health of the code, refactoring complex logic in the lib/ utilities and making sure we stuck to best practices. This makes the application much easier to maintain and build upon down the road.

All these efforts transformed the "Super Time Tracker UI" from a promising prototype into a fully-fledged, feature-rich application that's ready to be a part of your daily routine.

My Experience with GitHub Copilot

Honestly, GitHub Copilot was like having an expert co-pilot sitting right next to me throughout this whole challenge. Its ability to grasp what I was trying to do and instantly suggest relevant code really sped up development in so many areas.

Here's how Copilot became my secret weapon:

Quick Starts: Whenever I needed a new component (components/*.tsx), API route (app/api/**/*.ts), or utility function (lib/*.ts), Copilot was there, quickly dishing out the initial boilerplate. It saved me so much time on those repetitive setup tasks.
Anticipating My Needs: While I was busy polishing features or building new ones, Copilot's intelligent code completion was incredible. It suggested function calls, variable names, and logical structures, often knowing exactly what I was about to type next, especially with data manipulation and UI logic.
Help with Tidying Up: When I was refactoring more complex parts of the application, Copilot would chime in with suggestions for cleaner code, more efficient algorithms, and better variable names. It genuinely helped me write better, more maintainable code.
A Personal Tutor: If I was dabbling with a new pattern or integrating a library I wasn't super familiar with, Copilot was like an instant reference. It gave me helpful examples and usage patterns, significantly flattening the learning curve.
Catching Potential Issues: By suggesting common patterns and best practices, Copilot helped me write more robust code, which I'm sure prevented some bugs from even appearing. And when issues did pop up, its context-aware suggestions often nudged me towards the right fix.
Even Testing (if I had asked!): While I didn't explicitly ask it to generate tests this time, I know Copilot's knack for creating test cases based on existing code would have been incredibly useful for ensuring everything new and modified was rock-solid.

Essentially, Copilot felt like an extension of my own thinking, offering lightning-fast prototyping and smart assistance that let me focus on the bigger picture—the architecture, the user experience, and ultimately, bringing the "Super Time Tracker UI" to its complete and polished state right on schedule for the challenge.

I shipped super-time-tracker-ui, a local web UI for my CLI time sheets

Cris Mihalache — Thu, 28 May 2026 19:37:42 +0000

The short version

If you live in the terminal but still wish your time sheets had a real interface, I built the thing for you. It's called super-time-tracker-ui and it's now on npm.

npm install -g super-time-tracker-ui
stt-ui

That's it. The stt-ui command boots a local server and opens your browser to a full time tracking dashboard. No accounts required, no cloud required, no setup wizard.

Why I made it

I have a CLI called super-time-tracker that stores everything in a plain JSON file at ~/.super-time-tracker/db.json. The CLI is great for quick check ins and check outs, but reviewing a month of work in a terminal is rough. Pie charts in ASCII only get you so far.

So instead of bolting a clunky reporting command onto the CLI, I made a web UI that reads the exact same database file. Same data, two front ends. Track from the terminal, review in the browser, and they stay in sync because they're literally pointing at the same file. When the UI loads, it even migrates and dedupes the database on the fly so old data keeps working.

What it actually does

The home screen is the tracker. You check in with a description and inline @tags, watch the live timer, and check out when you're done. Entries pile up under the active sheet and you can do real work on them:

Edit, move between sheets, split, and merge entries
Archive things you want out of the way without deleting them
Bulk move or bulk delete a whole selection at once
Resume a past entry with one click
Attach, edit, and delete timestamped notes on any entry

Sheets work like separate timesheets. Create them, rename them, archive them, switch between them with keyboard shortcuts. Tag filtering supports both "match any" and "match all" modes.

The reporting dashboard

This is the part the CLI could never do well. There's a proper analytics view with:

A tag pie chart so you can see where the hours actually went
Daily bar charts and weekday breakdowns
An activity heatmap, the GitHub contributions style grid
Trend cards that compare periods
A month in review summary
Flexible date range picking with handy shortcuts
Focus goals and gentle nudges

You can set a weekly focus target, define your working hours, and pick a focus sheet. If you forget to log anything for a while, the app nudges you. If you're slacking on your target, it lets you know without being annoying about it. It's the accountability buddy that doesn't judge.

A built in Pomodoro timer

There's a real Pomodoro view with configurable work and break cycles. It ties into the tracker, so a focus session and a tracked entry can move together. Desktop notifications fire when a phase ends, so you can stop staring at the countdown.

AI descriptions, your key, your call

Writing entry descriptions gets boring. The app can generate a concise description for you from your current text and any notes you attached. You bring your own API key and pick the provider:

OpenAI
Claude
Google AI

Keys live in your own preferences and the request goes straight to the provider you chose. Skip this entirely if it's not your thing. Nothing depends on it.

Optional cloud sync

By default everything is local and offline. But if you want your sheets on more than one machine, there's optional Supabase sync. Sign in, then push and pull manually or let it sync automatically. Turn it on only if you want it.

The little things that make it pleasant

A command palette so you can jump anywhere fast
Keyboard shortcuts everywhere, with customizable quick actions
Light, dark, and system themes plus a few accent palettes
Desktop and in app notifications
It's a PWA, so you can install it and use it offline
Display knobs for time format, duration format, week start day, compact lists, seconds in the timer, and a live timer in the tab title

Backup, restore, import, and markdown export for your data

Under the hood

It's a Next.js 16 app on React 19, styled with Tailwind 4. The npm package ships a standalone build plus the stt-ui launcher. The launcher frees the port if a previous instance is still running, waits for the server to come up, then opens your default browser. You can override the port, the bind host, or tell it to skip opening a browser.

PORT=8080 stt-ui
STT_UI_HOSTNAME=0.0.0.0 stt-ui
stt-ui --no-open

You'll need Node 20 or newer.

Try it

npm install -g super-time-tracker-ui
stt-ui

Then open http://127.0.0.1:3000 and start tracking. It's MIT licensed and the source lives on GitHub. If you find a bug or want a feature, open an issue. I'd love to hear how you use it.

Happy tracking.

A Powerful Node.JS CLI Time Tracker ⏱️🚀

Cris Mihalache — Thu, 23 Apr 2026 07:33:29 +0000

Introducing super-time-tracker: A Node.js CLI Time Tracker (Rebuilt)

After using my own track-time-cli for a while, I found myself wanting more — more commands, more flexibility, and a cleaner experience overall. So I rebuilt it from the ground up, gave it a new name, and published it as super-time-tracker.

Introducing super-time-tracker, a Node.js CLI utility for tracking the time you spend on your projects, with natural language time input, tags, notes, and rich reporting commands.

It is a Node.js CLI app written in TypeScript. Like its predecessor, it supports natural language for task start and end times (e.g., 2 hours and 24 minutes ago or forty five minutes ago), and most commands accept flags to render durations in human-readable form or show times as relative.

Getting Started

Install it with your package manager of choice:

npm i -g super-time-tracker

The entry point is stt. By default, running stt with no arguments shows the currently active time sheet entry.

All data is stored in ~/.super-time-tracker/db.json — a plain JSON file you can version-control in a git repo to back up your entries as they grow.

Run stt --help to view all supported commands.

A Note on Command Aliases

All commands have short aliases. For example, stt list is the same as stt l, and stt sheet is the same as stt s. I'll use the short forms throughout this post. Check stt --help for the full list.

Timesheets 📚

A task in super-time-tracker is a timesheet entry that belongs to a timesheet. Timesheets represent any grouping of tasks — typically a project or a client.

To view all timesheets, run stt ss. This command also accepts --today, --yesterday, --since <natural language time>, --filter <substring>, and --concise to narrow down the output.

Managing Timesheets

To create or switch to a timesheet, run stt s [name]. Running stt s with no name displays the currently active sheet. A default sheet named main is created on first run.

New in this version:

stt s --rename <new name> — rename the active sheet in place.
stt s <name> --delete — delete a sheet by name.

Tracking Tasks ⏱️

To check in to a new entry, run stt i <description>. If you started working earlier and forgot to check in, use --at:

stt i --at '2 hours and 24 minutes ago' crafting something

You can also target a specific sheet with --sheet, attach tags with --tags, or add an opening note with --note:

stt i --sheet work --tags @frontend @bugfix fixing the modal
stt i --note 'starting with a plan' writing the architecture doc

To end a task, run stt o, optionally with --at or --note:

stt o --at '5 minutes ago'
stt o --note 'wrapped up, tests passing'

Notes

A new addition in this version is the dedicated note command, which attaches a timestamped note to the active entry:

stt n pair with alice on the widget

You can also attach notes to specific past entries:

stt n --sheet work --entry 32 --at '30 minutes ago' got unblocked

Resuming Entries

stt r resumes (clones) the most recent entry as a fresh active entry. You can also resume a specific entry by ID, on a different sheet, or with overrides:

stt r --entry 32
stt r --at '10 minutes ago' --tags @foo updated description

Editing Entries

The edit command got a significant upgrade. You can now rewrite an entry's start/end times, update its tags, or delete it by ID:

stt e --entry 32 --start '10am' --end '11:30am'
stt e --entry 32 --tags @new @tags
stt e --entry 32 --delete

Viewing Tasks 📃

List

stt l lists entries from the past 24 hours. It accepts --since, --all, --all-sheets, --filter, --concise, and -r (relative timestamps). For example:

stt l --since '7 days ago' --all-sheets -r -h

Convenience Commands

There are dedicated commands for common time windows:

stt t — entries from today
stt y — entries from yesterday
stt w — a week summary; supports --total for a per-day aggregate, plus --since, --all-sheets, and --filter

Breakdown

stt b displays total durations broken down by day, weekday, and hour — useful for spotting patterns in when you work most. It accepts --today, --yesterday, --since, --all-sheets, and --filter.

Useful Flags

Nearly every command supports:

-h — render durations in human-readable format (e.g., 1 hour, 36 minutes instead of 1:36:18)
-r — show times as relative (e.g., 3 hours ago instead of an absolute timestamp)

Example Workflow

Here's a typical day with super-time-tracker:

stt s work
stt i --at '2 hours and 24 minutes ago' crafting something
stt n pair with alice on the widget
stt o
stt l --since '4 hours ago'
stt t
stt w

What's New vs. track-time-cli

If you used the old track-time-cli (tt), here's a quick summary of what changed:

Notes — new dedicated command for attaching timestamped notes to entries
Tags — first-class support on stt i, stt r, and stt e
Sheet management — rename and delete sheets directly from the CLI
resume upgrades — resume with a time override, tag override, or description override
edit upgrades — rewrite start/end times from natural language, update tag sets
breakdown — improved with weekday and hour-of-day breakdowns in addition to per-day totals
sheets — now supports --today, --yesterday, --since, and --filter
New command: stt (instead of tt)

I haven't covered every flag and option in this post — check out the README and the full stt --help output for the complete picture.

Any feedback, comments, or suggestions are very welcome. Happy tracking! ⏱️

A Powerful Node.JS CLI Time Tracker ⏱️🚀

Cris Mihalache — Thu, 23 Apr 2026 07:33:28 +0000

Introducing super-time-tracker: A Node.js CLI Time Tracker (Rebuilt)

Introducing super-time-tracker, a Node.js CLI utility for tracking the time you spend on your projects, with natural language time input, tags, notes, and rich reporting commands.

Getting Started

Install it with your package manager of choice:

npm i -g super-time-tracker

The entry point is stt. By default, running stt with no arguments shows the currently active time sheet entry.

All data is stored in ~/.super-time-tracker/db.json — a plain JSON file you can version-control in a git repo to back up your entries as they grow.

Run stt --help to view all supported commands.

A Note on Command Aliases

Timesheets 📚

A task in super-time-tracker is a timesheet entry that belongs to a timesheet. Timesheets represent any grouping of tasks — typically a project or a client.

To view all timesheets, run stt ss. This command also accepts --today, --yesterday, --since <natural language time>, --filter <substring>, and --concise to narrow down the output.

Managing Timesheets

To create or switch to a timesheet, run stt s [name]. Running stt s with no name displays the currently active sheet. A default sheet named main is created on first run.

New in this version:

stt s --rename <new name> — rename the active sheet in place.
stt s <name> --delete — delete a sheet by name.

Tracking Tasks ⏱️

To check in to a new entry, run stt i <description>. If you started working earlier and forgot to check in, use --at:

stt i --at '2 hours and 24 minutes ago' crafting something

You can also target a specific sheet with --sheet, attach tags with --tags, or add an opening note with --note:

stt i --sheet work --tags @frontend @bugfix fixing the modal
stt i --note 'starting with a plan' writing the architecture doc

To end a task, run stt o, optionally with --at or --note:

stt o --at '5 minutes ago'
stt o --note 'wrapped up, tests passing'

Notes

A new addition in this version is the dedicated note command, which attaches a timestamped note to the active entry:

stt n pair with alice on the widget

You can also attach notes to specific past entries:

stt n --sheet work --entry 32 --at '30 minutes ago' got unblocked

Resuming Entries

stt r resumes (clones) the most recent entry as a fresh active entry. You can also resume a specific entry by ID, on a different sheet, or with overrides:

stt r --entry 32
stt r --at '10 minutes ago' --tags @foo updated description

Editing Entries

The edit command got a significant upgrade. You can now rewrite an entry's start/end times, update its tags, or delete it by ID:

stt e --entry 32 --start '10am' --end '11:30am'
stt e --entry 32 --tags @new @tags
stt e --entry 32 --delete

Viewing Tasks 📃

List

stt l lists entries from the past 24 hours. It accepts --since, --all, --all-sheets, --filter, --concise, and -r (relative timestamps). For example:

stt l --since '7 days ago' --all-sheets -r -h

Convenience Commands

There are dedicated commands for common time windows:

stt t — entries from today
stt y — entries from yesterday
stt w — a week summary; supports --total for a per-day aggregate, plus --since, --all-sheets, and --filter

Breakdown

Useful Flags

Nearly every command supports:

-h — render durations in human-readable format (e.g., 1 hour, 36 minutes instead of 1:36:18)
-r — show times as relative (e.g., 3 hours ago instead of an absolute timestamp)

Example Workflow

Here's a typical day with super-time-tracker:

stt s work
stt i --at '2 hours and 24 minutes ago' crafting something
stt n pair with alice on the widget
stt o
stt l --since '4 hours ago'
stt t
stt w

What's New vs. track-time-cli

If you used the old track-time-cli (tt), here's a quick summary of what changed:

Notes — new dedicated command for attaching timestamped notes to entries
Tags — first-class support on stt i, stt r, and stt e
Sheet management — rename and delete sheets directly from the CLI
resume upgrades — resume with a time override, tag override, or description override
edit upgrades — rewrite start/end times from natural language, update tag sets
breakdown — improved with weekday and hour-of-day breakdowns in addition to per-day totals
sheets — now supports --today, --yesterday, --since, and --filter
New command: stt (instead of tt)

I haven't covered every flag and option in this post — check out the README and the full stt --help output for the complete picture.

Any feedback, comments, or suggestions are very welcome. Happy tracking! ⏱️

Using Chat GPT To Generate Datasets 🤖

Cris Mihalache — Thu, 23 Apr 2026 00:53:30 +0000

Recently I used Chat GPT to generate mock data in JSON format.

This is extremely powerful, as you can describe what real data looks like in your prompt, and Chat GPT will generate data with realistic content in fields like descriptions, titles, tags, etc.

This is a sample of the data Chat GPT generated:

  {
    "id": 3,
    "description": "Implementing OAuth2 for user authentication",
    "tags": [
      "@feature",
      "@security"
    ],
    "start": "2024-02-22T03:11:03",
    "end": "2024-02-22T06:36:18"
  }

Notice how the description, tags, and duration are all realistic.

Example

To build the documentation website for track-time-cli, I needed a database with mock data to have realistic command output in the documentation content.

To get Chat GPT to generate them for me, I used the following prompt:

Generate 5 time sheet entries with realistic software development tasks as descriptions. Use the following schema:

        {
          "id": 1,
          "description": "writing documentation",
          "tags": [
            "@feature",
            "@docs"
          ],
          "start": "2024-02-21T18:26:45",
          "end": "2024-02-21T19:33:08"
        }

The entries should be sequential in time, of varying durations (between 5 minutes and 5 hours), and have realistic descriptions that fit the software development time sheet theme.

The output should be in JSON, an array of time sheet entries conforming to the provided schema example.

Note that I specified the number of entries (5) and the type of activity (realistic software development tasks) that should be mentioned in the description.

I defined the output schema by providing an example of a correctly formatted time sheet entry. I also specified that they should be sequential in time and have realistic durations as would be expected for the defined type of activity.

Result

This was the output:

[
  {
    "id": 1,
    "description": "Refactoring user interface code",
    "tags": [
      "@feature",
      "@frontend"
    ],
    "start": "2024-02-21T18:26:45",
    "end": "2024-02-21T22:39:32"
  },
  {
    "id": 2,
    "description": "Optimizing database queries for report generation",
    "tags": [
      "@performance",
      "@database"
    ],
    "start": "2024-02-21T22:39:32",
    "end": "2024-02-22T03:11:03"
  },
  {
    "id": 3,
    "description": "Implementing OAuth2 for user authentication",
    "tags": [
      "@feature",
      "@security"
    ],
    "start": "2024-02-22T03:11:03",
    "end": "2024-02-22T06:36:18"
  },
  {
    "id": 4,
    "description": "Weekly team sync-up meeting",
    "tags": [
      "@meeting",
      "@communication"
    ],
    "start": "2024-02-22T06:36:18",
    "end": "2024-02-22T10:16:24"
  },
  {
    "id": 5,
    "description": "Adding localization support for new languages",
    "tags": [
      "@feature",
      "@i18n"
    ],
    "start": "2024-02-22T10:16:24",
    "end": "2024-02-22T11:50:10"
  }
]

After running this prompt a few times to generate 16 entries, I placed them all in an array within a mock JSON database. The output of running track-time-cli's list command was the following:

 23:50 ▶ 97% ▶ xia ▶ f3rnox ▶ .track-time-cli ▶  main ▶ ✎ ▶ 2? ▶ $ ▶ tt l
* Showing sheets since 2/21/2024, 12:00:00 AM [yesterday]

- Sheet main (16 entries) [1:10:19:16]
    (1)   [9:28:26]  yesterday       ->  14 hours ago    Writing API documentation                           @feature @docs
    (2)   [16:51]    14 hours ago    ->  14 hours ago    Implementing user authentication module             @feature @backend
    (3)   [50:01]    14 hours ago    ->  13 hours ago    Designing database schema for new features          @design @database
    (4)   [2:04:11]  13 hours ago    ->  11 hours ago    Improving responsive design for mobile devices      @feature @frontend
    (5)   [2:29:48]  11 hours ago    ->  9 hours ago     Conducting user experience research                 @research @ux
    (6)   [1:42:30]  9 hours ago     ->  7 hours ago     Implementing caching for improved performance       @performance @backend
    (7)   [9:08]     7 hours ago     ->  7 hours ago     Weekly team retrospective meeting                   @meeting @team
    (8)   [39:52]    7 hours ago     ->  6 hours ago     Refining search algorithm                           @algorithm @backend
    (9)   [2:13:23]  6 hours ago     ->  4 hours ago     Reviewing and merging pull requests                 @review @version-control
    (10)  [1:08:12]  4 hours ago     ->  3 hours ago     Developing new feature for customer analytics       @feature @analytics
    (11)  [2:27:32]  3 hours ago     ->  21 minutes ago  Solving compatibility issues in cross-platform app  @bugfix @mobile
    (12)  [3:14:14]  21 minutes ago  ->  in 3 hours      Organizing backlog and prioritizing tasks           @planning @management
    (13)  [3:07:36]  in 3 hours      ->  in 6 hours      Upgrading server infrastructure                     @maintenance @devops
    (14)  [1:41:17]  in 6 hours      ->  in 8 hours      Creating automated tests for new API endpoints      @testing @automation
    (15)  [2:02:29]  in 8 hours      ->  in 10 hours     Troubleshooting server downtime issues              @maintenance @devops
    (16)  [43:46]    in 10 hours     ->  in 10 hours     Designing user interface for the upcoming module    @design @frontend

* 0 Sheets not shown. use --all to show

Conclusions

Clearly Chat GPT is a great tool for generating realistic datasets.

Try it out the next time you need some mock data with realistic textual content! 🚀

Build a typed CLI from scratch with Commander.js + Zod

Cris Mihalache — Wed, 22 Apr 2026 23:03:34 +0000

The problem with untyped CLIs

Commander.js is great for parsing arguments, but it hands you everything as string | undefined — regardless of what type you declared in the option definition. The <number> in .option("--count <number>") is cosmetic. What lands in your action handler is raw text from process.argv, and the coercion, validation, and type-narrowing is entirely on you. Most developers paper over this with parseInt(opts.count as string) and hope for the best. That works until a user passes "banana" and your tool crashes with a stack trace instead of a helpful message.

We already have the right tool for this: Zod. It's everywhere in the Node.js ecosystem for HTTP bodies, env vars, and config files — but rarely applied at the CLI layer. That's the gap this post fills. By the end you'll have a CLI that validates all inputs at the boundary, gives users readable error messages, and is fully typed end-to-end with no casts and no any.

1. Project scaffold

mkdir my-cli && cd my-cli
npm init -y
npm install commander zod
npm install -D typescript tsx @types/node
npx tsc --init

Three dependencies: commander for the CLI surface, zod for validation, tsx to run TypeScript directly during development without a compile step. Update tsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "dist"
  }
}

strict: true is non-negotiable here — it's exactly what catches the class of bugs we're solving. Wire up bin and scripts in package.json:

{
  "bin": { "my-cli": "./dist/index.js" },
  "scripts": {
    "dev": "tsx src/index.ts",
    "build": "tsc"
  }
}

2. Your first typed command

import { Command } from "commander";

const program = new Command();

program
  .name("my-cli")
  .option("--name <string>", "Your name")
  .option("--count <number>", "How many times to greet")
  .action((opts) => {
    console.log(opts);
  });

program.parse(process.argv);

Run it:

npx tsx src/index.ts --name Alice --count 3
# { name: 'Alice', count: '3' }

count is '3' — a string. Commander doesn't coerce types. If you do arithmetic with it you get string concatenation. If you type-guard with typeof opts.count === 'number' it always returns false. This is the gap Zod fills.

3. Enter Zod — schema-validate your options

Treat program.opts() the same way you'd treat an untrusted HTTP request body: validate at the boundary, only work with the parsed output. Define a schema and run opts through it:

import { z } from "zod";

const OptionsSchema = z.object({
  name: z.string().min(1, "Name cannot be empty"),
  count: z.coerce.number().int().positive().default(1),
});

program.action((opts) => {
  const options = OptionsSchema.parse(opts);

  for (let i = 0; i < options.count; i++) {
    console.log(`Hello, ${options.name}!`);
  }
});

z.coerce.number() calls Number(value) before validating, converting Commander's "3" to 3. If someone passes --count banana, Zod rejects it cleanly instead of silently producing NaN. .int().positive() enforces additional constraints without a single if statement. .default(1) makes the option optional — Zod fills it in. After .parse(), options has the inferred type { name: string; count: number } — no annotation required.

4. User-friendly validation errors

Right now a failed parse throws a raw ZodError JSON blob at the user. Fix that with a small reusable helper using safeParse():

import { ZodSchema } from "zod";

function parseOptions<T>(schema: ZodSchema<T>, opts: unknown): T {
  const result = schema.safeParse(opts);

  if (!result.success) {
    console.error("Invalid options:\n");
    result.error.issues.forEach((issue) => {
      console.error(`  --${issue.path.join(".")}  ${issue.message}`);
    });
    console.error("\nRun with --help for usage.\n");
    process.exit(1);
  }

  return result.data;
}

Before vs after, when --name is missing:

# Before
ZodError: [{"code":"too_small","path":["name"],"message":"Name cannot be empty"...}]

# After
Invalid options:

  --name  Name cannot be empty

Run with --help for usage.

This helper is generic — T is inferred from the schema, so the return type is always exactly right. opts is unknown, which correctly models the untrusted input. Replace all direct .parse() calls with parseOptions(schema, opts) going forward.

5. Scaling to subcommands

As your CLI grows, each command gets its own schema and calls the same helper — no copy-pasted validation logic:

const InitSchema = z.object({
  dir: z.string().default("."),
  force: z.boolean().default(false),
});

const RunSchema = z.object({
  name: z.string().min(1),
  count: z.coerce.number().int().positive().default(1),
});

program
  .command("init")
  .option("--dir <path>", "Target directory")
  .option("--force", "Overwrite existing files")
  .action((opts) => {
    const options = parseOptions(InitSchema, opts);
    console.log(`Initializing in ${options.dir}`);
  });

program
  .command("run")
  .option("--name <string>", "Your name")
  .option("--count <number>", "How many times to greet")
  .action((opts) => {
    const options = parseOptions(RunSchema, opts);
    for (let i = 0; i < options.count; i++) {
      console.log(`Hello, ${options.name}!`);
    }
  });

Inside the init action, options has type { dir: string; force: boolean }. Inside run, it's { name: string; count: number }. TypeScript infers these separately from each schema — accessing options.name in the init handler is a compile error, not a runtime surprise.

6. Help menus and `.env` support

Commander generates --help automatically from your .option() descriptions — you already have it for free. One gotcha: Zod's .default() values don't appear in Commander's help output. Mirror them manually in the third argument to .option():

.option("--count <number>", "How many times to greet", "1")

For .env support, merge environment variables into opts before parsing. Zod doesn't care where values originate — it just validates the final object:

import "dotenv/config";

program.command("run").action((cliOpts) => {
  const merged = {
    name: process.env.CLI_NAME,
    count: process.env.CLI_COUNT,
    ...cliOpts, // CLI flags win over env vars
  };
  const options = parseOptions(RunSchema, merged);
});

Env vars as defaults, CLI flags as overrides — one schema validates both.

7. Publishing to npm

Add a shebang as the very first line of src/index.ts (before imports):

#!/usr/bin/env node

Build, make the output executable, test locally with npm link, then publish:

npm run build
chmod +x dist/index.js
npm link
my-cli run --name Cris --count 3  # test it
npm unlink my-cli
npm publish --access public

Verify with npx my-cli run --name Cris --count 3 — if that works, you're done.

Wrapping up

The pattern in one line: Commander owns the surface, Zod owns the contract. Commander parses and routes. Zod coerces, validates, defaults, and types. The parseOptions helper — 15 lines — is the glue, and it scales to any number of subcommands without modification.

This isn't CLI-specific either. The same schema-at-boundary approach applies to HTTP bodies, env vars, and config files. Validate everything at every input boundary, work only with validated data inside your logic, and an entire category of runtime bugs stops existing.

The full source is on GitHub: [link to your repo]

Next up: adding --json output mode and stdin piping so your CLI composes cleanly in shell pipelines.

Found this useful? Drop a reaction or leave a comment — feedback helps me prioritise what to cover next in this series.

Stop Guessing npm Package Names — Let a CLI Do It

Cris Mihalache — Wed, 22 Apr 2026 22:32:04 +0000

You've finished building a neat little utility. You open a terminal, type npm publish, and then… stall. What do you name the thing?

You try json-stream-parser — taken. stream-json-parser — also taken. parse-json-stream — taken too, and it's a completely different package. You spend 20 minutes bouncing between the npm registry website and your terminal before settling on something you're not even happy with.

I've been through that loop more times than I'd like to admit, so I built a small tool to short-circuit it: gen-package-name.

What it does

gen-package-name is a CLI utility that:

Asks you for a short description of your package (or accepts keywords directly)
Extracts meaningful keywords from that description
Generates a set of name candidates using those keywords
Checks each candidate against the npm registry in real time
Lets you regenerate until you find something you like

The whole flow takes about 30 seconds.

Getting started

Install globally:

npm install -g gen-package-name

Or just run it once with npx:

npx gen-package-name

Interactive mode (the happy path)

Run it with no arguments and it walks you through everything:

gen-package-name

You'll be prompted for a description like "parse json streams efficiently". It strips stop words, extracts the signal (parse, json, streams), and generates 5 name candidates using a mix of patterns — adjective-noun, verb-noun, noun-type, and combinations like verb-keyword-cli. Each candidate gets checked against the registry and marked available or taken.

If you don't love the batch, you can regenerate as many times as you want. When you pick a name that's already taken, it fetches and prints the existing package's metadata so you know what you're up against.

Non-interactive and CI-friendly modes

For scripting and pipelines, there are a few flags worth knowing:

Generate names from a description, no prompts:

gen-package-name -d "http request retry logic" -n

Pass keywords directly, show only available names, output JSON:

gen-package-name -k http,retry,fetch -c 10 -a -j

The JSON output is machine-readable, so you can pipe it into other tools or use it in a script that automates your publish workflow.

Quick availability check for a specific name:

gen-package-name --check my-package-name

Fetch registry metadata for any existing package:

gen-package-name --info chalk --json

How the name generation works

The generator builds name candidates by randomly combining words from several pools:

Adjectives — words like tiny, fast, safe, sharp
Verbs — words like parse, watch, build, resolve
Nouns — a curated list plus your own keywords injected at the top
Package type suffixes — lib, cli, kit, util, core, and so on

The patterns it uses are the same conventions that popular npm packages already follow: adjective-noun (tiny-emitter, fast-glob), verb-noun (parse-json, watch-config), and noun-type (router-kit, cache-lib). When you supply two or more keywords, it also generates keyword-keyword pairs — things like http-client or auth-token — which tend to be the most memorable names.

Candidates are validated against npm's naming rules before they're even checked against the registry (lowercase alphanumeric and hyphens, no leading/trailing hyphens, max 214 chars), so you never get back something that would fail at publish time anyway.

Full CLI reference

Usage: gen-package-name [options]

Options:
  -V, --version          print version and exit
  -d, --description      describe the package (keywords extracted automatically)
  -k, --keywords <list>  comma- or space-separated keyword seeds
  -c, --count <n>        number of names to generate (default: 5)
  -a, --available-only   only output names available on npm
  -j, --json             emit machine-readable JSON
  -n, --non-interactive  skip prompts; print results and exit
  --check <name>         check whether a specific name is available
  --info <name>          fetch npm registry metadata for a package
  --no-color             disable colored output
  -h, --help             display help

Stack

The package is written in TypeScript, targets Node.js ≥ 16, and uses:

Commander.js for argument parsing
Inquirer for the interactive prompts
chalk for colored output
package-json to query the npm registry

No exotic dependencies, no network calls beyond the registry lookups.

DEV Community: Cris Mihalache

Productivity Perfected: How I Wrapped Up the Super Time Tracker UI

What I Built

Demo

The Comeback Story

My Experience with GitHub Copilot

I shipped super-time-tracker-ui, a local web UI for my CLI time sheets

The short version

Why I made it

What it actually does

The reporting dashboard

A built in Pomodoro timer

AI descriptions, your key, your call

Optional cloud sync

The little things that make it pleasant

Backup, restore, import, and markdown export for your data

A Powerful Node.JS CLI Time Tracker ⏱️🚀

Introducing super-time-tracker: A Node.js CLI Time Tracker (Rebuilt)

Getting Started

A Note on Command Aliases

Timesheets 📚

Managing Timesheets

Tracking Tasks ⏱️

Notes

Resuming Entries

Editing Entries

Viewing Tasks 📃

List

Convenience Commands

Breakdown

Useful Flags

Example Workflow

What's New vs. track-time-cli

A Powerful Node.JS CLI Time Tracker ⏱️🚀

Introducing super-time-tracker: A Node.js CLI Time Tracker (Rebuilt)

Getting Started

A Note on Command Aliases

Timesheets 📚

Managing Timesheets

Tracking Tasks ⏱️

Notes

Resuming Entries

Editing Entries

Viewing Tasks 📃

List

Convenience Commands

Breakdown

Useful Flags

Example Workflow

What's New vs. track-time-cli

Using Chat GPT To Generate Datasets 🤖

Example

Result

Conclusions

Build a typed CLI from scratch with Commander.js + Zod

The problem with untyped CLIs

1. Project scaffold

2. Your first typed command

3. Enter Zod — schema-validate your options

4. User-friendly validation errors

5. Scaling to subcommands

6. Help menus and .env support

7. Publishing to npm

Wrapping up

Stop Guessing npm Package Names — Let a CLI Do It

What it does

Getting started

Interactive mode (the happy path)

Non-interactive and CI-friendly modes

How the name generation works

Full CLI reference

Stack

Links

6. Help menus and `.env` support