Commands Reference

Complete CLI commands reference for the bgit tool

Most Used Commands

Detailed Documentation

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 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]
bgit clone <url> --no-bind

Details

Clones a GitHub repository using the effective identity's SSH configuration. Accepts HTTPS or SSH URLs and converts them automatically. By default, cloned repositories are auto-bound to the effective identity. Use --no-bind to skip.

Example

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

bgit remote fix

Fix repository remote URL for active identity (Legacy/Advanced)

Usage

bgit remote fix

Details

Legacy/advanced command. Converts the current repository's origin remote URL to use the active user's SSH config. In normal flow, bgit check and pre-push checks guide/fix this automatically.

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 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 setup

Run one-time setup

Usage

bgit setup

Details

Initializes bgit configuration, installs managed pre-push safety checks, updates SSH managed section, and configures first-run defaults.

bgit init

Initialize bgit on your system (Deprecated)

Usage

bgit init

Details

Deprecated. Use bgit setup instead. This command is kept for backward compatibility and routes users to the setup flow.

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 check

Run pre-push safety checks manually

Usage

bgit check

Details

Validates repo owner identity, active user, git config, and remote URL alignment. This is also used by the managed pre-push hook installed during setup.

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 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 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 (Deprecated)

Usage

bgit setup-ssh

Details

Deprecated. Use bgit setup instead. This command is kept for backward compatibility and manual SSH-agent workflows.

bgit prompt

Print effective identity for shell prompt integration

Usage

bgit prompt
bgit prompt --plain

Details

Outputs the effective identity for the current path. Use --plain for alias-only output, intended for shell prompt integrations.

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

# One-time setup
bgit setup

# Add your work account
bgit add

# Add your personal account
bgit add

# Switch identity
bgit use work

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

# Run safety check
bgit check

# Push as usual
git push

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

bgit converts to identity-specific hostname format automatically (for example: git@github.com-work-gh: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