Command Line Interface

Use GitHub Desktop from the command line to open repositories, clone projects, and automate workflows

GitHub Desktop includes a command-line interface (CLI) that allows you to interact with the application from your terminal, making it easy to integrate Desktop into scripts and workflows.

Installation

The CLI is bundled with GitHub Desktop and available after installation:

macOS

# CLI is available as 'github' after installation
github --help

On Windows, you may need to add the GitHub Desktop installation directory to your PATH environment variable.

Usage

The CLI supports three main operations: opening repositories, cloning repositories, and getting help.

Basic Syntax

github [command] [options] [arguments]

Commands

Open Repository

Open the current directory or a specific path in GitHub Desktop:

Open Current Directory

github

The CLI implementation:

app/src/cli/main.ts

const [firstArg, secondArg] = args._
const pathArg = firstArg === 'open' ? secondArg : firstArg
const path = resolve(pathArg ?? '.')
run(`--cli-open=${path}`)

Clone Repository

Clone a repository by URL or owner/name format:

1. Clone by URL

   github clone https://github.com/owner/repo
   
2. Clone by shorthand

   github clone owner/repo
   

   The CLI automatically expands owner/repo format to the full GitHub URL:

   app/src/cli/main.ts

   const url =
     urlArg && /^[^\/]+\/[^\/]+$/.test(urlArg)
       ? `https://github.com/${urlArg}`
       : urlArg
   
3. Clone specific branch

   github clone owner/repo --branch develop
   github clone owner/repo -b develop
   

   app/src/cli/main.ts

   if (typeof args.branch === 'string') {
     run(`--cli-clone=${url}`, `--cli-branch=${args.branch}`)
   } else {
     run(`--cli-clone=${url}`)
   }
   

Help

Display usage information:

github --help
github -h
github help

CLI Implementation

The CLI uses minimist for argument parsing and platform-specific launching:

app/src/cli/main.ts

import { join, resolve } from 'path'
import parse from 'minimist'
import { execFile, spawn } from 'child_process'

const args = parse(process.argv.slice(2), {
  alias: { help: 'h', branch: 'b' },
  boolean: ['help'],
})

Argument Parsing

The CLI supports these options:

Option	Alias	Type	Description
--help	-h	boolean	Display help information
--branch	-b	string	Specify branch when cloning

Platform-Specific Launching

macOS

if (process.platform === 'darwin') {
  execFile('open', [
    '-n',                           // Open new instance
    join(__dirname, '../../..'),    // Path to .app bundle
    '--args',
    ...args
  ], callback)
}

The CLI spawns GitHub Desktop as a detached process, allowing the terminal session to continue independently.

Usage Examples

Open Current Repository

cd ~/projects/my-app
github

Open Specific Repository

github ~/projects/another-repo

Clone and Open

1. Clone from GitHub

   github clone facebook/react
   
2. Clone specific branch

   github clone facebook/react --branch main
   
3. Clone from URL

   github clone https://github.com/microsoft/vscode.git
   

Workflow Integration

Integrate the CLI into shell scripts:

Setup Script

#!/bin/bash
# Clone and open a repository

REPO="$1"
BRANCH="${2:-main}"

if [ -z "$REPO" ]; then
  echo "Usage: $0 <owner/repo> [branch]"
  exit 1
fi

echo "Cloning $REPO (branch: $BRANCH)..."
github clone "$REPO" --branch "$BRANCH"

Error Handling

The CLI includes comprehensive error handling:

app/src/cli/main.ts

const run = (...args: Array<string>) => {
  function cb(e: unknown | null, stderr?: string) {
    if (e) {
      console.error(`Error running command ${args}`)
      console.error(stderr ?? `${e}`)
      process.exit(
        typeof e === 'object' && 'code' in e && typeof e.code === 'number'
          ? e.code
          : 1
      )
    }
  }
  // ... launch logic
}

Help Output

app/src/cli/main.ts

const usage = (exitCode = 1): never => {
  process.stderr.write(
    'GitHub Desktop CLI usage: \n' +
      '  github                            Open the current directory\n' +
      '  github open [path]                Open the provided path\n' +
      '  github clone [-b branch] <url>    Clone the repository by url or name/owner\n' +
      '                                    (ex torvalds/linux), optionally checking out\n' +
      '                                    the branch\n'
  )
  process.exit(exitCode)
}

Advanced Usage

Opening Recently Cloned Repository

After cloning a repository, GitHub Desktop automatically opens it:

# Clone and immediately start working
github clone microsoft/typescript
# GitHub Desktop opens with the repository ready

Path Resolution

The CLI resolves paths relative to the current working directory:

app/src/cli/main.ts

const path = resolve(pathArg ?? '.')
run(`--cli-open=${path}`)

This means you can use relative paths:

# Open parent directory's repository
github ..

# Open sibling directory
github ../other-repo

Environment Variables

The CLI removes the ELECTRON_RUN_AS_NODE environment variable to ensure proper launching:

app/src/cli/main.ts

delete process.env.ELECTRON_RUN_AS_NODE

Common Patterns

Quick Project Setup

Clone and Install

# Clone repository
github clone owner/repo

# In another terminal, install dependencies
cd repo
npm install

# GitHub Desktop is already open and ready

Integration with Git Workflows

#!/bin/bash
# Create and open a new feature branch

FEATURE="$1"

if [ -z "$FEATURE" ]; then
  echo "Usage: $0 <feature-name>"
  exit 1
fi

# Create branch
git checkout -b "feature/$FEATURE"

# Open in GitHub Desktop
github .

echo "Feature branch created and opened in GitHub Desktop"

Troubleshooting

Command Not Found

1. Check installation

   Verify GitHub Desktop is installed and the CLI is available:

   which github  # macOS/Linux
   where github  # Windows
   
2. Add to PATH (Windows)

   On Windows, add the GitHub Desktop installation directory to your PATH:

   $env:Path += ";$env:LOCALAPPDATA\GitHubDesktop"
   
3. Restart terminal

   After installation or PATH changes, restart your terminal to pick up the new commands.

Repository Not Opening

If a repository doesn’t open:

1. Verify the path exists:

   ls -la /path/to/repo
   

2. Check it’s a Git repository:

   cd /path/to/repo
   git status
   

3. Check GitHub Desktop logs for error messages

Clone Fails

If cloning fails:

• Verify repository exists: Check the URL or owner/repo format
• Check authentication: Ensure you’re logged into GitHub Desktop
• Network connectivity: Verify you can reach github.com
• Branch exists: If specifying a branch, ensure it exists in the repository

Related

• Repository Management
• Branch Management
• Shell Integration