Documentation

DevSwitch Documentation

Everything you need to install, configure, and master DevSwitch for your Git workflow.

Overview

DevSwitch is a cross-platform Electron desktop app that simplifies managing multiple Git identities and SSH keys. Whether you juggle work and personal accounts, or manage dozens of client projects, DevSwitch lets you switch SSH keys and Git configs with a single click.

✓Supports ED25519 and RSA keys

✓GitHub OAuth integration

✓Automatic SSH config management

✓Encrypted passphrase storage

✓Cross-platform: macOS, Linux, Windows

✓Auto-sync from ~/.ssh directory

Installation

Download the latest release for your platform from the Downloads page or from GitHub Releases.

macOS

.dmg

Open DMG and drag to Applications.

Linux

.AppImage

chmod +x and run the AppImage.

Windows

.exe

Run the installer, follow the prompts.

Prerequisites: Node.js v18+, Git, OpenSSH (usually pre-installed on macOS/Linux).

Updates

The desktop app auto-updates via GitHub Releases, which is the canonical source for installers and the latest*.yml update feeds. This site mirrors those builds under /git-switch/<os>/ as a convenience download page. If a platform shows an older version here, grab the newest build directly from GitHub Releases.

Command-Line Tool (devswitch)

DevSwitch ships a standalone, cross-platform devswitch command-line tool for Windows, macOS, and Linux. It needs Node.js 18+ and shares the same profile database as the desktop app, so changes made in one appear instantly in the other.

Install Options

npm (recommended, all platforms) — npm handles PATH for you.

npm install -g devswitch-cli

Standalone installer — no npm required, just Node.js 18+.

curl -sSL https://devswitch.in/init/cli.sh | bash

Bundled with the desktop app — the Linux .deb package auto-installs the CLI alongside the app.

Command Reference

Most commands accept a --json flag for scripting. A <profile> argument matches by name, username, email, or id (partial, case-insensitive).

Command	Aliases	Description
help	—	Show all commands and usage.
version	—	Print the installed CLI version.
list	ls	List all saved profiles.
use <profile>	switch	Switch to (activate) a profile.
current	whoami	Show the currently active profile.
add	create	Create a new profile.
remove <profile>	rm	Delete a profile.
show <profile>	view	Show details for a profile.
sync	—	Import existing SSH keys into profiles.
test <profile>	—	Test the SSH connection for a profile.
pubkey <profile>	—	Print the public key for a profile.
clone <url> [dir]	—	Clone a repo using a profile (--profile <name>).
logs	—	Show CLI activity logs.
path	—	Print the data directory path.
doctor	—	Diagnose environment and configuration issues.
completion	—	Install tab completion (with --install).
import <file>	—	Import profiles (supports --new-ssh, --password).
export <file>	—	Export profiles (supports --with-ssh, --password-protected).
backup	—	Backup the current state (with --output).
autobackup [on\|off]	—	Toggle auto-backup of profiles.
rename <old> <new>	—	Rename a profile name.
duplicate <src> <dst>	—	Duplicate a profile (with a new key).
edit <profile>	—	Edit a profile's settings.
stats <profile>	—	Show profile usage statistics.
update	—	Update the CLI and Desktop App.
install app	—	Install the Desktop App installer.

Data Location

The CLI and desktop app read and write the same on-disk profile store:

Linux: ~/.config/devswitch
macOS: ~/Library/Application Support/devswitch
Windows: %APPDATA%\devswitch

Override the data directory by setting the DEVSWITCH_DATA_DIR environment variable.

Shell Autocompletion

DevSwitch CLI now features smart tab autocompletion! You can autocomplete commands and even your profile names dynamically.

1.After installing the CLI, run the setup once:

devswitch --setup

2.Reload your terminal or source your shell config (e.g., ~/.bashrc or ~/.zshrc).
3.Type devswitch then press Tab. It will show subcommands, and if you type devswitch use [Tab], it will suggest your actual profile names!

Getting Started

After installing DevSwitch, follow these steps to create your first profile:

1.Launch DevSwitch from your Applications folder.
2.Click "Create Profile" on the home screen.
3.Enter a profile name (e.g., "Work"), GitHub username, and email.
4.Choose an SSH key option: Generate new (recommended), use default, or import existing.
5.Click "Create Profile" to save.
6.Click the profile card to activate it — your SSH config and Git credentials update instantly.

SSH Key Management

DevSwitch handles the full lifecycle of SSH keys — generation, import, registration, and agent management.

Generate a New Key

Select "Generate New Key" when creating a profile. Choose the algorithm:

ED25519 (Recommended)

Modern, compact, and highly secure. Supported by all major Git hosts.

RSA 4096-bit

Compatible with older systems. Larger keys but widely supported.

Using a Profile-Specific SSH Host

DevSwitch creates unique host aliases in your SSH config:

# ~/.ssh/config (auto-generated by DevSwitch)
Host github.com-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/work_ed25519

Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/personal_ed25519

Use the alias when cloning:

git clone git@github.com-work:your-org/repo.git

Managing Profiles

Each profile stores a name, email, GitHub username, and an associated SSH key. Profiles are isolated — switching one doesn't affect others.

Create

Click "Create Profile" → fill details → select SSH key.

Edit

Open a profile card → click Edit → update any field.

Switch

Click any profile card to activate it instantly.

Delete

Open a profile → click Delete → confirm. Optionally remove key files.

Rename / Duplicate

Easily rename a profile or duplicate it to create a new one with a fresh SSH key.

Stats

View usage statistics for your profiles to see which ones you use the most.

GitHub OAuth Integration

Connect your GitHub account to auto-upload SSH keys directly from DevSwitch.

1.Go to GitHub Settings → Developer settings → OAuth Apps → New OAuth App.
2.Set Homepage URL to http://localhost:5173 and Callback URL to http://localhost:<PORT>/oauth/callback.
3.Copy the Client ID and Client Secret into a .env file: GITHUB_CLIENT_ID=... GITHUB_CLIENT_SECRET=...
4.Restart DevSwitch. A "Connect GitHub" button will appear on each profile view.

Auto-Sync Existing Keys

If you already have SSH keys configured, use the Sync button to import them automatically.

DevSwitch scans ~/.ssh for all key pairs, reads your existing SSH config, and creates profiles for any unmanaged keys. It extracts email addresses from public key comments where possible.

Keys already managed by DevSwitch are skipped to prevent duplicates.

Data Management

DevSwitch provides robust tools to import, export, and backup your profiles and settings securely.

Import / Export

Safely move your profiles between machines using password-protected encrypted exports.

--password-protected Encrypt your export file with a password.
--with-ssh Include SSH keys in your export.
--new-ssh Generate fresh SSH keys for all profiles on import.

Backups

Never lose your configuration with manual and automatic backups.

devswitch backup Create an instant snapshot of your current state.
devswitch autobackup on Automatically backup profiles when changes occur.

Security

DevSwitch takes security seriously. Here is how your data is protected:

Encrypted Storage

All profile data including passphrases is stored using electron-store with AES encryption.

No Plain-Text Passwords

Passphrases are encrypted at rest and cleared from memory after use.

Local-Only

DevSwitch does not send any data to external servers. Everything stays on your machine.

SSH Agent

Keys are loaded into the SSH agent for the current session only and do not persist after reboot.