Mastering GitHub with the GitHub CLI

AlexLearn Supplement · Hands-On Reference for Every Participant

A practical guide to installing the GitHub CLI, creating repositories, and maintaining your projects — no browser required.

Why GitHub?

GitHub is where your Alex-powered work lives. It is the version control layer that:

Preserves history — every change is recorded and reversible
Enables collaboration — your team sees exactly what changed and why
Drives deployment — pushing to main can instantly publish a website, run tests, or trigger a workflow
Stores Alex’s memory — Alex’s cognitive architecture (the .github/ folder) travels with your repo

1 · Install the GitHub CLI

The GitHub CLI (gh) lets you create repos, open pull requests, manage secrets, and trigger workflows — all from your terminal.

Windows

# Option A — winget (built into Windows 11)
winget install --id GitHub.cli

# Option B — Scoop
scoop install gh

# Option C — download the MSI installer
# https://github.com/cli/cli/releases/latest

macOS

# Homebrew
brew install gh

Linux (Debian / Ubuntu)

(type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) \
&& sudo mkdir -p -m 755 /etc/apt/keyrings \
&& wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg \
   | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
&& sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
   | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update && sudo apt install gh -y

Verify the installation

gh --version
# gh version 2.x.x (...)

2 · Authenticate

gh auth login

Follow the prompts:

Choose GitHub.com
Choose HTTPS as your preferred protocol
Choose Login with a web browser and paste the one-time code when prompted

Verify you are logged in:

gh auth status
# ✓ Logged in to github.com account your-username

3 · Create a Repository

From an existing local folder

This is the most common case — you have work on your laptop and want it on GitHub.

# Navigate to your project folder
cd ~/my-project

# Initialize git if it isn't already
git init
git add -A
git commit -m "initial commit"

# Create the remote and push in one step
gh repo create my-project \
  --public \
  --description "My Alex-powered project" \
  --push \
  --source .

--public makes the repo visible to everyone. Use --private for private repos.

From scratch (empty repo)

gh repo create my-new-project --public --clone
cd my-new-project

Fork an existing repo

gh repo fork fabioc-aloha/AlexLearn --clone

4 · Clone a Repository

# Clone by name (your own repo)
gh repo clone my-project

# Clone someone else's repo
gh repo clone fabioc-aloha/AlexLearn

# Classic git clone also works
git clone https://github.com/username/repo-name.git

5 · The Daily Git Workflow

These four commands cover 90% of everyday version control.

# 1. Pull the latest changes before you start
git pull

# 2. Make your changes, then stage them
git add -A               # stage everything
git add src/file.ts      # or stage one file

# 3. Commit with a message
git commit -m "feat: add persona selector to homepage"

# 4. Push to GitHub
git push

Commit message conventions

Prefix	When to use
`feat:`	New feature or content
`fix:`	Bug fix or correction
`docs:`	Documentation only
`ci:`	Workflow / pipeline changes
`chore:`	Maintenance, dependencies
`refactor:`	Code restructuring, no behavior change

6 · Branching

Work on a branch to keep main stable.

# Create and switch to a new branch
git checkout -b feature/new-workshop-content

# Push the branch
git push -u origin feature/new-workshop-content

# Open a pull request from the CLI
gh pr create \
  --title "Add engineers workshop content" \
  --body "Adds STUDY-GUIDE and TALKING-POINTS for the engineers persona"

# Merge via CLI once approved
gh pr merge --squash

7 · Managing Your Repository

View status and history

git status                 # what has changed
git log --oneline -10      # last 10 commits
git diff                   # what changed in unstaged files

Repository information

gh repo view               # view your current repo in the terminal
gh repo view --web         # open it in the browser

Releases

# Create a release tag
gh release create v1.0.0 \
  --title "AlexLearn v1.0 — Workshop Launch" \
  --generate-notes

Secrets (for CI/CD)

# Add a secret (e.g. Azure deploy token)
gh secret set MY_SECRET --body "secret-value"

# List secrets (names only — values are never shown)
gh secret list

8 · Useful Shortcuts

# Open the repo in the browser
gh browse

# View recent workflow runs
gh run list

# Watch a running workflow
gh run watch

# View issues
gh issue list

# Create an issue
gh issue create --title "Bug: broken link on homepage" --body "..."

9 · Setting Up Alex in a New Repo

After you create a repo and clone it, initialize Alex:

Open the folder in VS Code
Open GitHub Copilot Chat
Type: Alex: Initialize Architecture

Alex will scaffold the full .github/ cognitive architecture into your repo. Commit and push:

git add -A
git commit -m "feat: initialize Alex cognitive architecture"
git push

10 · `.gitignore` Essentials

A .gitignore file tells git which files never to track. Create one in any project root:

# Dependencies
node_modules/
__pycache__/
.venv/

# Build output
dist/
build/
out/

# Environment secrets
.env
.env.local
*.key

# OS noise
.DS_Store
Thumbs.db

# IDE
.vscode/settings.json   # optional — many teams DO commit this
*.vsix

Generate one for your stack at gitignore.io.

Quick Reference Card

Task	Command
Log in	`gh auth login`
Create repo from folder	`gh repo create <name> --push --source .`
Clone a repo	`gh repo clone <owner/repo>`
Stage all changes	`git add -A`
Commit	`git commit -m "message"`
Push	`git push`
Pull	`git pull`
New branch	`git checkout -b branch-name`
Open PR	`gh pr create`
View repo in browser	`gh repo view --web`
Add CI secret	`gh secret set NAME --body "value"`
Run list	`gh run list`

AlexLearn · Created by Fabio Correa · correax.com