gh-issues - GitHub Issues CLI Tool

A command-line interface tool built with oclif, TypeScript, and Node.js to manage GitHub issues and Google Calendar reminders from the terminal. Created while learning CLI development, TypeScript, and API integrations.

TypeScript Node.js oclif GitHub API Google Calendar API
View Project →

Video Preview

gh-issues CLI Demo

About

gh-issues is a command-line interface tool built as a learning project using the oclif framework to manage GitHub issues and Google Calendar reminders directly from the terminal. This project was created while exploring CLI development, TypeScript, Node.js, and API integrations. The tool provides a streamlined way to view, create, and manage GitHub issues, as well as add reminders to Google Calendar, all without leaving the command line.

As a learning project, gh-issues helped me understand how to build CLI applications with oclif, work with multiple APIs (GitHub and Google Calendar), handle OAuth authentication, and create user-friendly terminal interfaces. It demonstrates proficiency in TypeScript, async programming, and building developer tools that improve workflow efficiency by integrating issue tracking with calendar reminders.

Tech Stack

Core Technologies

  • TypeScript: Strongly typed JavaScript for building robust CLI applications with better error handling and developer experience
  • Node.js: Runtime environment for executing JavaScript/TypeScript on the server-side and building CLI tools
  • JavaScript: Core language features and Node.js APIs for file system operations, HTTP requests, and process management

CLI Development

  • oclif Framework: Built using oclif, a powerful CLI framework by Salesforce that provides command structure, argument parsing, plugin system, auto-documentation, and TypeScript support
  • GitHub API: Integration with GitHub’s REST API for issue management operations using personal access tokens
  • Google Calendar API: Integration with Google Calendar API for adding reminders, using OAuth 2.0 authentication
  • Terminal Interface: User-friendly command-line interface with proper error handling and output formatting

Key Features Implemented

  • Issue Management: View all issues (npx issues all), create new issues (npx issues create), and manage GitHub issues from the command line
  • Google Calendar Reminders: Add reminders to Google Calendar for issues (npx issues add reminder), integrating issue tracking with calendar management
  • Repository Integration: Connect to GitHub repositories and manage issues across different projects
  • Command Structure: Organized commands using oclif’s command structure for different operations
  • Dual API Authentication:
    • GitHub API authentication using personal access tokens
    • Google Calendar API authentication using OAuth 2.0 with desktop app credentials
  • Error Handling: Robust error handling for network issues, authentication failures, and invalid inputs
  • Plugin System: Extensible architecture using oclif’s plugin system for additional functionality

Learning & Insights

This project was a valuable learning experience in building developer tools and working with APIs. As a CLI application, it provided hands-on practice with terminal interfaces, async programming, and creating tools that developers actually use.

CLI Development with oclif

Building a command-line tool with oclif taught me about modern CLI architecture and framework-based development. oclif provided built-in features like command structure, argument parsing, flag handling, auto-documentation, and plugin support. I learned how to organize commands hierarchically, handle flags and options with type safety, and leverage oclif’s testing helpers. The framework’s auto-documentation feature helped me understand how to generate help text automatically. This experience showed me how using a well-designed framework can accelerate CLI development while maintaining code quality and extensibility.

TypeScript for CLI Tools

Using TypeScript for a CLI application provided excellent practice with type safety in a Node.js environment. I learned to type API responses, handle async operations with proper typing, and create type definitions for command arguments and options. The type system caught many potential bugs during development and made the codebase more maintainable.

API Integration

Working with multiple APIs (GitHub and Google Calendar) taught me about different authentication methods and API patterns. With GitHub API, I learned about personal access tokens, REST API consumption, rate limiting, and handling API responses. With Google Calendar API, I learned about OAuth 2.0 flow, desktop app credentials, token storage, and handling authorization flows. I learned to structure API calls, handle different response types, manage authentication securely, and integrate multiple services into a single application. This experience gave me practical knowledge of how to work with different API authentication patterns and integrate third-party services.

Async Programming

CLI tools often need to make multiple API calls and handle asynchronous operations. This project helped me understand Promise handling, async/await patterns, error propagation in async code, and how to provide feedback to users during long-running operations. I learned to handle network timeouts, retry logic, and graceful error handling.

Developer Experience

Building a tool for other developers taught me about developer experience (DX) principles. I learned to design clear command syntax, provide helpful error messages, create intuitive workflows, and ensure the tool is easy to install and use. This project helped me understand what makes developer tools effective and enjoyable to use.

Testing CLI Applications

Testing command-line applications presented unique challenges. I learned to test command execution, mock API calls, test error scenarios, and verify output formatting. This experience taught me about testing strategies for CLI tools and how to ensure reliability in terminal-based applications.

Package Management & Distribution

Creating a distributable CLI tool with oclif required understanding npm package structure, bin scripts, command installation, and version management. oclif’s built-in support for distribution made it easier to create installable packages. I learned about creating executable commands that can be run via npx, handling dependencies, and preparing packages for distribution. The tool can be installed and run globally or via npx without requiring local installation. This experience gave me insight into how modern CLI tools are packaged and distributed to users, making them easily accessible.

This learning project was instrumental in understanding how developer tools are built and what makes them effective. It provided practical experience with TypeScript, API integration, and creating tools that improve developer workflows.