Commands Reference

Complete reference for all bgit commands

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 "john@work.com" --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 git@github.com 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 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

# Initialize bgit
bgit init

# Add your work account
bgit add

# Add your personal account
bgit add

# List all identities
bgit list

Daily Usage

# Switch to work account
bgit use work

# Clone with correct SSH config
bgit clone https://github.com/company/repo.git

# Switch to personal
bgit use personal

Troubleshooting

# Check active identity
bgit active

# Verify configuration
bgit sync

# Fix issues
bgit sync --fix

Fix Existing Repo

# Switch to correct identity
bgit use work

# Inside the repo, fix remote URL
cd my-project
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: git@github.com-work:org/repo.git

Pro Tips

  • •Use descriptive aliases like "work", "personal", "client-acme"
  • •Run bgit sync --fix if you manually modify your .gitconfig or .ssh/config
  • •Always check bgit active before starting work on a new project
  • •bgit doesn't wrap git commands - after switching, just use git normally

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

Read DocumentationAsk a Question