Skip to main content
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: 
# 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: 
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:
OptionAliasTypeDescription
--help-hbooleanDisplay help information
--branch-bstringSpecify branch when cloning

​
Platform-Specific Launching

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: 
#!/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 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

Build docs developers (and LLMs) love

Get started for freeTalk to us