gh auth switch: Switch Multiple GitHub CLI Accounts & Git Config

📅 Created: 2023/01/04, Updated: 2026/11/03 ⏱️ Estimated reading time ~5 mins (1,087 words)

Switch multiple GitHub CLI accounts instantly with ‘gh auth switch -u’ and ‘gh auth setup-git’, plus Git author email isolation (includeIf) & GH_TOKEN fixes.

Table of Contents

TL;DR: The Fastest Way to Switch Multiple Accounts in GitHub CLI ( gh auth switch ) ⚡
1. Registering and Switching Multiple Accounts with gh auth switch
2. Syncing git push and git clone Authentication with gh auth switch
1. Why Does git push Still Return Permission denied After Switching?
2. Solution: Configure gh auth setup-git and Reset Conflicting Helpers
3. Crucial: Isolating Git Commit Authors ( user.name / user.email ) with includeIf
1. 3.1 Add includeIf Rules to ~/.gitconfig
2. 3.2 Create the Environment-Specific Config Files
4. Troubleshooting Flowchart: When Account Switching Fails
1. Pitfall 1: GH_TOKEN / GITHUB_TOKEN Environment Variable Override
2. Pitfall 2: Role-Based Switching for AI Coding Agents (Claude Code / Antigravity)
5. Custom Aliases: Switching by Role Name ( personal / work )
1. Pattern A: Lightweight Alias Wrapping Official gh auth switch -u (Recommended)
2. Pattern B: File-Based hosts.yml.${profile} Backup Aliases (Legacy Method)
6. Summary: Comparison of Multi-Account Approaches
1. References
Related Articles
Revision History

TL;DR: The Fastest Way to Switch Multiple Accounts in GitHub CLI ( `gh auth switch` ) ⚡

Task	Command	Notes
Check active & logged-in accounts	`gh auth status`	Shows active account ( `Active account: true` )
Toggle between 2 accounts	`gh auth switch`	Instant switch on `github.com` (GitHub CLI v2.40.0+)
Switch to a specific username	`gh auth switch -u <username>`	Best for scripts or 3+ accounts
Sync `git push` / `git pull` HTTPS auth	`gh auth setup-git`	Configures Git to use the active `gh` credential
Add a second account without overwriting	`gh auth login`	Stores both tokens safely in OS Keyring
Fix `gh auth switch` not working	`unset GH_TOKEN GITHUB_TOKEN`	Environment variables override keyring credentials

When I first wrote this article in February 2023, GitHub CLI ( gh ) had no built-in way to store and switch between multiple accounts on the same host. Back then, the only practical workaround was copying ~/.config/gh/hosts.yml.${profile} files back and forth via custom shell aliases.

Starting with GitHub CLI v2.40.0 (released December 2023) , GitHub introduced native multi-account support via gh auth switch . Today (verified on gh version 2.102.0 ), you can log in to multiple accounts simultaneously and switch between them with a single native command—without manually overwriting config files:

# 1. Log in to an additional account (added alongside existing accounts without overwriting)
gh auth login

# 2. Check all logged-in accounts and see which one is currently active
gh auth status

# 3. Switch accounts (toggles immediately if you have 2 accounts on github.com)
gh auth switch

# 4. Switch non-interactively by specifying the username (for scripts or 3+ accounts)
gh auth switch -u kanji-shinohara

# 5. Sync Git HTTPS operations (git push / pull / clone) with the active gh account
gh auth setup-git

If all you need is to run gh pr create or gh issue list under a different account, gh auth switch is all it takes.

However, as someone who switches daily between work repositories and personal repositories on the same Mac, I repeatedly ran into three real-world pitfalls that gh auth switch alone does not solve:

git push authenticates under the switched account, but git commit still records your company email ( user.email ) in personal repositories (or vice versa).
A leftover GH_TOKEN or GITHUB_TOKEN environment variable silently overrides or blocks gh auth switch .
AI coding agents (Claude Code, Antigravity, etc.) and shared automation scripts work much better with abstract role names ( personal / work ) than hardcoded GitHub usernames.

In this guide, I will walk through the official gh auth switch workflow, how to solve all three pitfalls using a two-layer separation architecture, and how to configure role-based aliases for automation.

▲ Two-Layer Multi-Account Architecture: API/HTTPS Credential Switching (gh auth switch) + Commit Author Isolation (Git includeIf)

1. Registering and Switching Multiple Accounts with `gh auth switch`

1.1 Adding a Second Account ( `gh auth login` )

While already logged in to your first account (e.g., work-taro ), simply run gh auth login again and authenticate with your second account (e.g., kanji-shinohara ):

gh auth login -h github.com -p https -w

Modern versions of GitHub CLI store OAuth tokens in your OS keyring by default (macOS Keychain, Windows Credential Manager, or Linux Secret Service) rather than writing plaintext oauth_token strings into ~/.config/gh/hosts.yml .

1.2 Checking Active Status ( `gh auth status` )

Run gh auth status to inspect all registered accounts and verify which one has Active account: true :

$ gh auth status
github.com
  ✓ Logged in to github.com account kanji-shinohara (keyring)
  - Active account: true
  - Git operations protocol: https
  - Token: gho_************************************
  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'

  ✓ Logged in to github.com account work-taro (keyring)
  - Active account: false
  - Git operations protocol: https
  - Token: gho_************************************
  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'

If you want to inspect only the active account in a script or terminal prompt, use --active ( -a ) or query the API directly:

# Display only the currently active account
gh auth status --active

# Print only the active GitHub username (useful in pre-push scripts)
gh api user --jq '.login'

1.3 Switching the Active Account ( `gh auth switch` )

You can switch accounts in three ways depending on your setup:

# Option A: Toggle immediately when you have exactly two accounts on github.com
gh auth switch

# Option B: Specify the target username explicitly (best for scripts or 3+ accounts)
gh auth switch -u kanji-shinohara

# Option C: Specify both hostname and username (when using GitHub Enterprise Server)
gh auth switch --hostname github.company.internal -u work-taro

2. Syncing `git push` and `git clone` Authentication with `gh auth switch`

Why Does `git push` Still Return `Permission denied` After Switching?

One of the most common frustrations I hit was running gh auth switch -u kanji-shinohara , verifying Active account: true , and still getting remote: Permission to kanji-shinohara/repo.git denied to work-taro. (or Repository not found ) on git push .

This happens when Git’s own credential helper (such as macOS osxkeychain or Windows Credential Manager) caches an older token and intercepts HTTPS authentication before GitHub CLI is consulted.

Solution: Configure `gh auth setup-git` and Reset Conflicting Helpers

First, run the official setup command:

gh auth setup-git

If your OS default credential helper still overrides GitHub CLI, clear the https://github.com helper chain first with an empty string '' and register !gh auth git-credential explicitly:

# Clear any system-level credential helper for github.com
git config --global --replace-all 'credential.https://github.com.helper' ''

# Delegate github.com HTTPS credentials exclusively to GitHub CLI
git config --global --add 'credential.https://github.com.helper' '!gh auth git-credential'

Your ~/.gitconfig will now contain the following block, guaranteeing that git push and git pull immediately follow whichever account is active in gh auth switch :

[credential "https://github.com"]
    helper = 
    helper = !/opt/homebrew/bin/gh auth git-credential

3. Crucial: Isolating Git Commit Authors ( `user.name` / `user.email` ) with `includeIf`

Here is the trap that catches almost everyone: gh auth switch only switches your API and HTTPS authentication token. It never changes user.name or user.email in Git.

If you switch authentication to your personal account and run git commit , Git will still stamp your commits with your global user.email (often your company address). To eliminate human error, I pair gh auth switch with Git’s directory-based includeIf configuration so commit identities switch automatically based on folder path.

3.1 Add `includeIf` Rules to `~/.gitconfig`

# ~/.gitconfig
[user]
    name = Kanji Shinohara
    email = kanji.shinohara@example.com

# Automatically apply personal author identity inside ~/workspace/personal/
[includeIf "gitdir:~/workspace/personal/"]
    path = ~/.gitconfig-personal

# Automatically apply work author identity inside ~/workspace/work/
[includeIf "gitdir:~/workspace/work/"]
    path = ~/.gitconfig-work

[credential "https://github.com"]
    helper = 
    helper = !/opt/homebrew/bin/gh auth git-credential

3.2 Create the Environment-Specific Config Files

# ~/.gitconfig-personal
[user]
    name = Kanji Shinohara
    email = kanji.shinohara@gmail.com

# ~/.gitconfig-work
[user]
    name = Kanji Shinohara
    email = kanji.shinohara@company.co.jp

(Note: Make sure to include the trailing slash / in gitdir:~/workspace/personal/ so Git applies the rule recursively to all subdirectories.)

4. Troubleshooting Flowchart: When Account Switching Fails

When gh auth switch or git push does not behave as expected, walk through this diagnostic flow:

        flowchart TD
    A["Account mismatch or Permission denied<br/>on gh command or git push"] --> B{"Run gh auth status:<br/>Is GH_TOKEN / GITHUB_TOKEN active?"}
    B -- "Yes (Env var overrides keyring)" --> C["Run: unset GH_TOKEN GITHUB_TOKEN<br/>(Check .envrc / direnv or shell profile)"]
    B -- "No" --> D{"Does gh auth switch fail with<br/>a write operations error?"}
    D -- "Yes" --> E["A read-only token is overriding config:<br/>unset GH_TOKEN then gh auth switch -u <user>"]
    D -- "No" --> F{"Do gh commands work, but<br/>git push fails with 403 / 404?"}
    F -- "Yes" --> G["Git is using osxkeychain/manager cache:<br/>Reset credential.https://github.com.helper ''<br/>and re-run gh auth setup-git"]
    F -- "No" --> H["Token expired or missing scopes:<br/>gh auth login -h github.com -s repo,workflow,read:org"]
       

Pitfall 1: `GH_TOKEN` / `GITHUB_TOKEN` Environment Variable Override

If direnv ( .envrc ), an MCP server config, or a shell export sets GH_TOKEN or GITHUB_TOKEN , GitHub CLI prioritizes the environment variable over your keyring configuration:

$ gh auth switch
X Active account on github.com cannot be switched while GH_TOKEN environment variable is set

Always check gh auth status —if it reports (from GH_TOKEN) , run unset GH_TOKEN GITHUB_TOKEN before switching.

Pitfall 2: Role-Based Switching for AI Coding Agents (Claude Code / Antigravity)

In my daily workflow, AI coding agents (such as Claude Code and Antigravity) operate across both personal and work repositories. Rather than hardcoding specific GitHub usernames into shared agent instructions ( AGENTS.md ), I define a role-based alias ( gh switch-profile personal / gh switch-profile work ) so every automation rule can use a consistent command.

5. Custom Aliases: Switching by Role Name ( `personal` / `work` )

Pattern A: Lightweight Alias Wrapping Official `gh auth switch -u` (Recommended)

Add a switch-profile alias to ~/.config/gh/config.yml that maps role names to your GitHub usernames:

# ~/.config/gh/config.yml
git_protocol: https
aliases:
    switch-profile: >-
      !case "$1" in
        personal) gh auth switch -h github.com -u kanji-shinohara ;;
        work)     gh auth switch -h github.com -u work-taro ;;
        *)        echo "[ERROR] Usage: gh switch-profile <personal|work>" && exit 1 ;;
      esac && gh auth status --active

Now both human developers and AI agents can run a uniform pre-push command:

gh switch-profile personal && git push origin HEAD

Pattern B: File-Based `hosts.yml.${profile}` Backup Aliases (Legacy Method)

If you prefer storing separate hosts.yml.${profile_name} files on disk (when using --insecure-storage ), you can configure the four profile management aliases below in ~/.config/gh/config.yml :

git_protocol: https
aliases:
    create-profile: '![ -z "$1" ] && echo "[ERROR] Please specify the profile name." && exit 1; gh auth status && read -p "Do you want to create this profile? (y/N): " yn; case "$yn" in [yY]*) cp ~/.config/gh/hosts.yml ~/.config/gh/hosts.yml.$1 && echo "New hosts file created: ~/.config/gh/hosts.yml.$1";; esac'
    switch-profile: '![ -z "$1" ] && echo "[ERROR] Please specify the profile name." && exit 1; if [ -e ~/.config/gh/hosts.yml.$1 ]; then cp ~/.config/gh/hosts.yml.$1 ~/.config/gh/hosts.yml && gh auth status && echo "[INFO] Hosts file switched"; else echo "[ERROR] Hosts file not found: ~/.config/gh/hosts.yml.$1"; fi'
    delete-profile: '![ -z "$1" ] && echo "[ERROR] Please specify the profile name." && exit 1; read -p "Do you want to delete this profile? (y/N): " yn; case "$yn" in [yY]*) rm -f ~/.config/gh/hosts.yml.$1 && echo "Hosts file deleted: ~/.config/gh/hosts.yml.$1";; esac'
    list-profiles: '!ls ~/.config/gh/hosts.yml.* | sed -e "s|^.*hosts.yml.||" | sed -e "s|^|  - |"'

6. Summary: Comparison of Multi-Account Approaches

Criteria	1. Native `gh auth switch`	2. `gh auth switch` + Git `includeIf` + Role Alias (My Setup)	3. Legacy `hosts.yml` Copy
Ease of Setup	◎ Built-in (zero config)	○ Requires one-time `~/.gitconfig` & alias setup	△ Manual file backup needed
Token Security	◎ Encrypted in OS Keyring	◎ Encrypted in OS Keyring	△ Relies on plaintext `hosts.yml`
`git push` Auth Sync	○ (With `gh auth setup-git` )	◎ Explicit credential helper reset prevents cache bugs	○
Commit Author Isolation	✕ Does not switch `user.email`	◎ Auto-isolated per workspace folder	✕ Does not switch `user.email`
AI Agent / Script Friendly	○ (Requires `-u <username>` )	◎ Unified via `gh switch-profile personal`	○

Combining native gh auth switch (for OS keyring token management) with gh auth setup-git , includeIf (for commit email isolation), and a thin gh switch-profile role alias has completely eliminated Permission denied errors and wrong-email commits in my multi-account environment. The one feature I still hope to see in a future GitHub CLI release is native directory-scoped account selection (similar to Git’s includeIf ), which would remove the need to run a switch command altogether.

References

AI Benchmark Leaderboard (Nov 2026): Opus 5.5, Gemini 4, GPT-6

Nov 2026 LLM leaderboard: SWE-bench (86.8%), ARC-AGI (99.9%), Terminal-Bench & $2/$10 API pricing ac ... [Read more]

[2024-2026 History] Evolution of AI Coding Agents & Future Outlook: From Copilot to Claude Code, Antigravity, and Kiro — The Paradigm Shift from Chat to Autonomous Cowork

Comprehensive retrospective of the 2-year evolution of AI coding tools. Tracing the shift from GitHu ... [Read more]

AI Agent Long-Term Memory: Markdown SSOT, Hybrid GraphRAG & Token Cuts

Gen 3 AI agent memory architecture: replace binary vector DBs with Git Markdown SSOT & Hybrid GraphR ... [Read more]

Revision History

Date	Summary of Updates
2026/11/03	- Added quick command cheat sheet table at the top for instant `gh auth switch` and `gh auth setup-git` lookup
2026/10/26	- Completely modernized the guide around the official native `gh auth switch` command (GitHub CLI v2.40.0+) and OS keyring storage - Added a two-layer architecture combining Git HTTPS credential sync ( `gh auth setup-git` ) and directory-based commit Author isolation ( `includeIf` in `~/.gitconfig` ) - Added a troubleshooting decision flowchart (Mermaid) for `GH_TOKEN` conflicts and `Permission denied` on `git push` , plus role-based aliases ( `personal` / `work` ) for AI coding agents
2025/06/18	- Updated `yq` alias configuration quoting and error output examples
2023/12/31	- Added reference on switching GitHub accounts with the 1Password CLI plugin
2023/02/21	- Added notes on Git credential helper integration via `!gh auth git-credential`

CONT-AID PRODUCTS

Production AI Applications & Official Ecosystem

AI COACH & STUDIO

CandidLens

AI Mock Calls & 5-Axis Voice Analytics

Master conversation skills with realistic AI phone training and 5-axis feedback. Includes 16-lesson interactive academy and studio AI portraits.

AI Mock Call Voice Analytics AI Studio

Explore CandidLens

SMART EXPENSE & OCR

DEALER

Zero-Friction Bill Split with Smart OCR

Effortlessly snap receipts for instant AI itemization. Integrated with LINE for seamless group expense tracking and pain-free settlement.

Smart Receipt OCR LINE Auth Smart Split

Explore DEALER

AI GAME MASTER

Mingli

Interactive AI Party Game Host

Interactive AI personas (Fortune Teller, Butler, Bartender) host real-time games, challenges, and conversation starters for unforgettable gatherings.

AI Persona Host Party Games Icebreaker

Explore Mingli

⏳ Coming Soon

Download Production-Ready Multi-Agent Rules & Hooks

Get the complete configuration pack featured in this article: universal AGENTS.md, deterministic hooks.json, Git safety guardrails, and validation scripts tested across Antigravity, Kiro, Claude Code, and Codex.

Get Starter Kit (Coming Soon) ※ Currently in preparation on Gumroad. The download link will become active upon launch.