GitHub CLI Repository Tasks

You've mastered git clone, git push, and pull requests through your browser — but every time you switch to GitHub's web UI to create a repo, edit settings, or triage issues, you break your flow. That context switch costs you focus, and it makes automation nearly impossible. This lesson shows you how to master GitHub CLI for repository tasks, so you can create, configure, and manage repositories entirely from your terminal — and even script those actions for repeatable workflows.

The problem this lesson solves

Relying on the GitHub web interface for repository management creates a constant mental jump between your code editor and browser. Each click — whether it's creating a new repo, adding a collaborator, or opening an issue — interrupts your development rhythm. Worse, these manual steps are error-prone and impossible to repeat consistently across multiple projects.

Consider a typical scenario: you finish a feature, want to open a PR, but first you need to create a new repository on GitHub, set its description, add a license, and invite a teammate. Without GitHub CLI, that's five separate browser tabs. With gh, it's one command that can even be chained with your Git workflow. The problem isn't that the web UI is bad — it's that it doesn't belong inside your terminal-centric workflow.

By mastering GitHub CLI for repository tasks, you eliminate those interruptions, gain scriptable control over your repos, and align your tooling with the Git philosophy: everything happens locally, with precision.

Core concept / mental model

Think of GitHub CLI (gh) as a command-line bridge between your local Git repository and GitHub's remote API. It translates familiar Git commands into authenticated API calls, giving you the same power as the web UI — but with the speed and scriptability of a terminal tool.

Here's a simple analogy: if Git is your local engine for version control, GitHub CLI is the steering wheel that connects that engine to GitHub's cloud services. You still use Git for commits and branches, but gh handles the GitHub-specific actions like creating repos, managing PRs, and checking CI status.

Core components of GitHub CLI

• gh command: The main binary you install and invoke.
• Authentication: gh auth login stores your credentials securely, so every subsequent command is authorized.
• Repository context: gh detects the current repository from your local Git remote, so you don't need to specify it every time.
• Extensions: gh supports plugins that add even more functionality, extending its ecosystem.

The mental model to adopt: Git is for history, gh is for GitHub's platform features. When you need to interact with GitHub as a remote server — not just push/pull code — reach for gh.

How it works step by step

Let's break down the typical workflow of using GitHub CLI for repository tasks into a logical sequence. Each step builds on the previous one, and you'll see why gh shines at each stage.

Step 1: Install and authenticate

First, you need gh installed. On macOS, brew install gh; on Ubuntu, sudo apt install gh; on Windows, use winget install --id GitHub.cli. After installation, authenticate once with gh auth login. This creates a credential store that all subsequent commands use.

Step 2: Create a repository

You can create a repo from your current directory or from scratch. The command gh repo create takes flags like --public, --private, --description, and --license. If you already have a local Git repo, --source picks it up.

Step 3: Manage repository metadata

Once your repo exists, you can view and edit its details. gh repo view shows README and metadata; gh repo edit lets you change the description, homepage, and enable/disable features like issues and wiki.

Step 4: Interact with issues and PRs

Repository tasks often involve triaging issues or reviewing PRs. gh issue create, gh issue list, and gh pr create are your go-to commands. They integrate directly with your local branch, so you can open a PR without ever leaving the terminal.

Step 5: Automate and script

Because gh is a normal CLI tool, you can chain it with shell commands. Use it in CI pipelines, cron jobs, or custom scripts. This is where the real power lies — you can automate repo setup, bulk-update issues, or generate reports.

Step 6: Extend with aliases and extensions

gh alias set lets you create shortcuts for complex commands, while gh extension install adds new functionality. These keep your workflow lean and personalized.

Hands-on walkthrough

Let's put this into practice. We'll create a new repository, configure it, and open an issue — all from the terminal. Make sure you've installed and authenticated gh first.

Create a repository from a local directory

# Assume you have a local Git repo in ~/my-project
cd ~/my-project

# Create a private repo on GitHub, using local source
gh repo create my-project --private --source=. --remote=origin

# Verify the remote is set
 git remote -v

Expected output (first two lines might vary):

✓ Created repository my-project on GitHub
origin  https://github.com/yourusername/my-project.git (fetch)
origin  https://github.com/yourusername/my-project.git (push)

Edit repository metadata

# Change the description and enable wiki
gh repo edit --description "My awesome project" --enable-wiki

Expected output: (no output, just a success prompt) — you can verify with gh repo view --json description.

Create an issue from the terminal

git checkout -b feature/new-feature

# Create an issue to track the feature
gh issue create --title "Add new feature" --body "We need this feature for v2.0"

Expected output:

✓ Created issue #1 on yourusername/my-project

List issues and PRs

# List open issues
gh issue list --state open

# List PRs you've authored
git push -u origin feature/new-feature
git checkout main
git branch -D feature/new-feature

gh pr create --title "Add new feature" --body "Closes #1"
gh pr list --author @me

Expected output (abbreviated):

# issue list
Showing 1 of 1 open issue in yourusername/my-project
#1  Add new feature  about 1 minute ago

# pr list
Showing 1 of 1 open pull request in yourusername/my-project
#2  Add new feature  about 1 minute ago

Pro tip: Use gh repo view --web to instantly open the repo in your browser if you ever need the visual interface. It's the best of both worlds.

Compare options / when to choose what

You now have three ways to manage GitHub repository tasks: the web UI, GitHub CLI, and the GitHub REST API (via curl or scripts). Each has strengths. Here's a quick comparison:

Choose GitHub CLI when: - You're already working in the terminal and want to avoid context switching. - You need to automate routine tasks like creating repos or opening issues. - You're in a CI/CD pipeline where browser interaction isn't possible.

Choose the REST API directly when you need fine-grained control over API responses, or when you're building a service that interacts with GitHub at scale. For most developer workflows, GitHub CLI is the sweet spot.

Troubleshooting & edge cases

Even with gh, you'll hit snags. Here are common issues and how to resolve them.

gh not found

If you get command not found, you need to install GitHub CLI. Follow the official installation guide, then restart your terminal. Verify with gh --version.

Authentication errors: gh auth status shows logged out

Run gh auth login again and complete the browser-based flow. Ensure your token has the repo scope for private repos. If you're behind a proxy, set HTTPS_PROXY environment variable.

"Repository not found" when creating

If you're in a directory that's not a Git repo, gh repo create without --source creates a remote-only repo, but you might expect a local one. Ensure you've run git init first if you want a local repo, and use --source=. to link it.

gh repo create fails with permission denied

You may lack permission to create repos in your organization. Check your org settings or use a personal account. Also, token scope might be missing repo — regenerate your token with appropriate scopes.

Wrong remote URL after creation

If you want SSH instead of HTTPS, create the repo with --git-protocol ssh. You can also change the remote later:

git remote set-url origin git@github.com:yourusername/my-project.git

gh auth login hangs in headless environment

For CI or container, use a personal access token with gh auth login --with-token < token.txt. Make sure the token has the required scopes.

Pro tip: Use gh api user to test your authentication quickly. If it returns your user data, you're good to go.

What you learned & what's next

You've now mastered GitHub CLI for repository tasks. You can create and configure repos from the terminal, open issues and PRs, and even automate these actions. This skill directly supports your Git workflow by keeping you in the command line, reducing context switching, and enabling repeatable processes.

Specifically, you can: - Install and authenticate GitHub CLI - Create public/private repositories from local or remote - Edit repository metadata and toggles - Manage issues and pull requests - Compare CLI vs. web UI vs. REST API for different scenarios

Now that you're comfortable with repository management, the next logical step is to explore GitHub Actions — you can use gh to trigger workflows, monitor runs, and even create them programmatically. This will take your automation to the next level, making your entire development pipeline scriptable.

Keep practicing: try creating a test repo every time you start a new project, and soon it'll be second nature.