Commands Reference

Complete CLI commands reference for the bgit tool

Commands

Detailed Documentation

bgit init

Initialize bgit on your system

Usage

bgit init

Details

Sets up bgit configuration directory at ~/.bgit/ and prepares the system for managing multiple Git identities. Optional - bgit auto-initializes on first use.

bgit add

Add a new Git identity

Usage

bgit add
bgit add --alias work --name "John Doe" --email "[email protected]" --github "john-work"

Details

Launches an interactive wizard to configure a new identity. You'll be prompted for alias, name, email, GitHub username, and SSH key setup. You can also provide flags directly to skip prompts. Use --ssh-key to specify an existing SSH key path.

bgit list

List all configured identities

Usage

bgit list
bgit ls

Details

Displays all identities you've configured. The currently active identity is marked with a → symbol. You can also use the short alias "ls".

bgit use

Switch to a different identity

Usage

bgit use <alias>
bgit use -u <github-username>
bgit use -m <email>

Details

Switches your Git configuration to use the specified identity. Updates your global .gitconfig and SSH configuration. You can switch by alias (default), GitHub username (-u), or email (-m). On Windows, automatically starts SSH agent and loads keys.

Example

bgit use work

bgit active

Show the currently active identity

Usage

bgit active

Details

Displays which identity is currently being used for Git operations, including name, email, GitHub username, and SSH key path.

bgit clone

Clone a repository with correct SSH config

Usage

bgit clone <url> [directory]

Details

Clones a GitHub repository using the active user's SSH configuration. Accepts any GitHub URL format (HTTPS or SSH) and automatically converts it to use the correct SSH key for the active identity.

Example

bgit clone https://github.com/user/repo.git

bgit remote fix

Fix repository remote URL for active identity

Usage

bgit remote fix

Details

Converts the current repository's origin remote URL to use the active user's SSH config. Run this inside a git repository after switching identities to fix authentication issues.

bgit remote restore

Restore remote URL to standard GitHub format

Usage

bgit remote restore

Details

Converts the current repository's origin remote URL back to standard GitHub format. Useful before uninstalling bgit or when you want to revert to normal [email protected] URLs.

bgit sync

Validate and fix Git/SSH configuration

Usage

bgit sync
bgit sync --fix

Details

Checks that your Git and SSH configurations match the active identity. Validates user.name, user.email, SSH key existence, and file permissions. Use --fix flag to automatically correct any issues.

Example

bgit sync --fix

bgit workspace

Create workspace folders with automatic identity binding

Usage

bgit workspace
bgit workspace --path ~/code
bgit workspace --users work,personal
bgit workspace --list
bgit workspace --remove work

Details

Creates organized workspace directories for each identity. All repositories cloned within a workspace folder automatically use that identity, regardless of the global active user. Use --list to view configured workspaces, --remove to delete a workspace binding.

Example

bgit workspace --path ~/projects

bgit bind

Bind current repository to a specific identity

Usage

bgit bind
bgit bind --user work
bgit bind --force
bgit bind --remove

Details

Binds the current repository to a specific identity. The binding persists regardless of the global active user. Use --user to specify identity, --force to override existing binding, --remove to unbind.

Example

bgit bind --user work

bgit status

Show current identity status and bindings

Usage

bgit status

Details

Displays comprehensive identity status including: active global identity, current location, effective identity (workspace/binding/global), configured workspaces, and repository bindings. Helps understand which identity will be used for the current context.

bgit doctor

Diagnose and fix configuration issues

Usage

bgit doctor
bgit doctor --network
bgit doctor --fix

Details

Runs comprehensive diagnostics on your bgit setup. Checks config validity, SSH directory/key permissions (700/600), SSH agent status, git config, and optionally network connectivity to GitHub. Use --fix to automatically correct permission issues.

Example

bgit doctor --fix

bgit delete

Remove an identity

Usage

bgit delete <alias>

Details

Removes an identity from bgit. Confirms before deletion and optionally deletes SSH key files. Clears active user if deleted identity was active.

Example

bgit delete old-work

bgit update

Update an identity's SSH key

Usage

bgit update <alias> --ssh-key <path>

Details

Updates the SSH key for an existing identity. Useful for adding a key to a user created without one, or changing to a new key. Automatically updates SSH config.

Example

bgit update work --ssh-key ~/.ssh/new_key

bgit setup-ssh

Setup SSH agent and load keys

Usage

bgit setup-ssh

Details

Sets up SSH agent and loads SSH keys for all configured identities. On Windows, starts the SSH agent service and sets it to automatic startup. On Linux/macOS, provides instructions if SSH agent isn't running.

bgit uninstall

Safely uninstall bgit

Usage

bgit uninstall
bgit uninstall --force
bgit uninstall --skip-repos

Details

Safely uninstalls bgit by scanning for repositories with bgit remote URLs and restoring them to standard GitHub format. Removes bgit SSH config entries and configuration directory. Use --skip-repos to skip repository scanning, --force to skip confirmation.

bgit --version

Show bgit version

Usage

bgit --version

Details

Displays the current version of bgit.

bgit help

Show help information

Usage

bgit help
bgit <command> --help

Details

Displays help information and available commands. Use --help with any command to see its specific options.

Common Workflows

First Time Setup

# Add your work account
bgit add

# Add your personal account
bgit add

# List all identities
bgit list

Using Workspaces

# Create workspace folders
cd ~/projects
bgit workspace

# Clone in workspace - auto identity!
cd ~/projects/work
bgit clone https://github.com/company/repo.git

Troubleshooting

# Run diagnostics
bgit doctor

# Auto-fix permission issues
bgit doctor --fix

# Check current status
bgit status

Bind Existing Repo

# Bind repo to identity
cd my-project
bgit bind --user work

# Fix remote URL
bgit remote fix

# Now git push/pull works!

Tip: Use bgit clone

The easiest way to clone is with bgit clone which automatically uses the correct SSH config:

bgit clone https://github.com/org/repo.git

Alternatively, you can use identity-specific hostname format manually: [email protected]:org/repo.git

Pro Tips

•Use bgit workspace to auto-switch identity by folder
•Run bgit doctor when SSH authentication fails
•Use bgit status to see which identity will be used
•Bind repos with bgit bind for sticky identity

Need more help? Check out the full documentation or ask the community

Read Documentation Ask a Question