cli-gh: GitHub Command Line Interface

0.0.9 · active · verified Wed Apr 22

cli-gh (GitHub CLI - ghc) is a command-line interface tool designed to interact with GitHub directly from your terminal. Currently at version 0.0.9, it is in active early development, implying that its API and features are subject to frequent changes and potential instability. The tool aims to provide a simple, intuitive, and cross-platform way to manage GitHub resources such as repositories, issues, pull requests, branches, collaborators, and user profiles. It uses GitHub Personal Access Tokens (PATs) for secure authentication. While it offers a comprehensive set of commands for common GitHub operations, its differentiator lies in its focused approach to provide core GitHub functionalities through a streamlined terminal experience, in contrast to the broader, more integrated offerings of the official GitHub CLI. There is no specified release cadence at this early stage.

Common errors

```
Error: Command not found: cli-gh
```
cause The cli-gh package was not installed globally, or the npm global bin directory is not in your system's PATH.

fix Run `npm install -g cli-gh` to install it globally. Verify your PATH environment variable includes the directory where npm installs global packages (e.g., `npm root -g`).
```
Authentication failed: Invalid Personal Access Token. Please provide a valid PAT.
```
cause The GitHub Personal Access Token (PAT) provided during `cli-gh auth login` is either incorrect, expired, or does not have the necessary scopes.

fix Generate a new PAT on GitHub with appropriate scopes (e.g., `repo`, `read:org`, `workflow` for full functionality) and re-run `cli-gh auth login` to update your credentials.
```
GraphQL Error: Resource not accessible by integration
```
cause The PAT used for authentication does not have sufficient permissions (scopes) to perform the requested operation.

fix Review the GitHub API documentation for the specific command you are trying to execute and ensure your PAT includes all required scopes. Generate a new PAT with broader permissions if necessary.

Warnings

breaking As cli-gh is in version 0.0.9, its API and command structure are highly unstable. Future versions are likely to introduce breaking changes without major version bumps, requiring frequent updates to scripts and workflows.
Fix: Refer to the latest documentation and changelogs before updating. Pin to exact patch versions if stability is critical.
gotcha Authentication relies on GitHub Personal Access Tokens (PATs). Storing PATs insecurely (e.g., in plaintext files committed to source control) poses a significant security risk, as they grant broad access to your GitHub account.
Fix: Always use environment variables, secure credential managers, or the interactive `cli-gh auth login` flow. Ensure PATs have the minimum required scopes and are rotated regularly.
gotcha Installing CLI tools globally (`npm install -g`) can sometimes lead to version conflicts or path issues, especially if multiple CLI tools with similar commands or dependencies are present on the system.
Fix: Consider using `npx` for one-off commands or local installations within a project if global installation causes conflicts. Ensure your PATH variable is correctly configured.
gotcha The official GitHub CLI, `gh`, is a widely adopted and actively maintained tool from GitHub itself. While cli-gh offers a different approach, developers might unintentionally confuse the two or find cli-gh's feature set less comprehensive or up-to-date compared to the official alternative.
Fix: Understand the scope and differences between `cli-gh` and the official `gh` CLI. If integrating with a larger GitHub ecosystem or needing broader features, evaluate `gh` (https://cli.github.com).

Install

npm install cli-gh npm
yarn add cli-gh yarn
pnpm add cli-gh pnpm

Imports

cli-gh (command)
wrong:
```
import { cliGh } from 'cli-gh'
```
correct:
```
npm install -g cli-gh
```
cli-gh is a command-line interface (CLI) tool and is not designed for programmatic import or use within JavaScript/TypeScript applications. Its functionality is exposed solely through shell commands.

Quickstart

Demonstrates global installation, secure authentication with a GitHub PAT, listing existing repositories, and creating a new public repository from the command line.

npm install -g cli-gh

# Log in to GitHub using a Personal Access Token (PAT)
# Follow the interactive prompts to generate or input your PAT
cli-gh auth login

# List all repositories for the authenticated user
cli-gh repo list

# Create a new repository (example: 'my-new-repo')
cli-gh repo create my-new-repo --public --description "My awesome new project."

view raw JSON →