Getting Started

This guide will walk you through installing Ghit and setting up your first workflow.

Installation

Install Ghit globally using your preferred package manager:

pnpm

pnpm add -g ghit

npm

npm install -g ghit

yarn

yarn global add ghit

First Steps

1. Authenticate with GitHub

Run the login command to authenticate:

ghit login

This will:

• Open your browser to GitHub's OAuth flow
• Request necessary permissions
• Store your token securely in ~/.ghit/db.sqlite

If your current workspace already has GitHub credentials available through your git credential helper, Ghit can reuse that token automatically (when Use Current Repo for Commands is enabled in ghit config).

2. Set a Default Repository

Set a default repository to avoid typing owner/repo on every command:

ghit set-repo owner/repository-name

For example:

ghit set-repo toneflix/ghit

When Use Current Repo for Commands is enabled (default), commands run inside a git repository will use that workspace repo first.

3. Verify Your Setup

Check that everything is configured correctly:

ghit info

This displays:

• Your authentication status
• Current default repository
• Configuration details

Working with Issues

Interactive Mode

Launch the interactive issues dashboard:

ghit issues

This lets you:

• Browse all issues in your repository
• View detailed information
• Close or reopen issues
• Edit titles and descriptions
• Delete issues

Creating Issues

Create a single issue:

ghit issues:create --title "Bug: Login fails" --body "Description here"

Bulk Operations

Seed multiple issues from a directory of markdown files:

ghit issues:seed ./issues-directory

Update existing issues:

ghit issues:update ./issues-directory

Delete multiple issues:

ghit issues:delete --start 1 --end 50

Generated API Commands

Ghit can generate commands directly from GitHub's OpenAPI specification.

Generate Commands

Run the generator once:

ghit generate:apis

This creates .ghit/apis.generated.js containing all GitHub REST API endpoints as CLI commands.

Using Generated Commands

Once generated, use any GitHub API endpoint as a command:

# Create an issue
ghit issues:create --title "New feature" --owner org --repo repo

# List repository issues
ghit issues:list --owner org --repo repo --state open

# Get a specific issue
ghit issues:get --owner org --repo repo --issue_number 42

# List organizations
ghit orgs:list-for-authenticated-user --per_page 50

TIP

The generated file is ignored by git (add .ghit/ to .gitignore). Regenerate when GitHub's API updates.

Configuration

View or modify configuration:

ghit config

Available options:

• debug — Enable detailed error messages
• token — Your GitHub personal access token
• useCurrentRepo — Auto-detect repository from current workspace and prefer git credential token when available
• default_repo — Default repository context

Next Steps

• Quick Start Guide for common workflows
• Commands Reference for all available commands
• API Documentation for generated command details