Switching Between NetBird Accounts with Profiles

Author: hakansa

public/docs-static/img/how-to-guides/profiles/manage-profiles.png

@@ -0,0 +1,206 @@
+# Switching Between NetBird Accounts with Profiles
+
+NetBird supports multiple profiles on a single device, making it easy to switch between work, home, or other networks.
+Only one profile is active at a time, and switching takes just a click.
+
+This feature also allows you to switch between self-hosted and cloud-hosted NetBird accounts seamlessly without needing
+to juggle multiple config files.
+
+<p>
+    <img src="/docs-static/img/how-to-guides/profiles/profiles.png" alt="profiles" className="imagewrapper"/>
+</p>
+
+Watch a short demo GIF demonstrating how profile switching works [here](/docs-static/img/how-to-guides/profiles/profiles.gif).
+
+## NetBird Profiles GUI Quickstart
+
+To get started with NetBird profiles:
+
+- Upgrade your client application to the latest NetBird version.
+- Run the GUI app
+
+You will see a `default` profile created automatically.
+
+Add more profiles by hovering over the default profile and clicking "Manage Profiles".
+After adding a new profile, select it to make it active.
+
+You can now change the NetBird settings, e.g., providing a self-hosted
+instance URL or allowing SSH. The new settings will be saved in the new profile. Click "Connect" to bring up the new profile.
+
+The consequent selection of your profiles from the menu will automatically trigger the NetBird client to connect to the network and authentication
+if needed.
+
+## Manage Profiles in the GUI
+
+* **Add** a new profile with a friendly name input.
+* **Delete** any inactive profile (trash icon).
+* **Active and default** profiles cannot be removed.
+
+<p>
+    <img src="/docs-static/img/how-to-guides/profiles/manage-profiles.png" alt="profiles" className="imagewrapper"/>
+</p>
+
+## What Is a Profile?
+
+A **profile** is your NetBird configuration bundle: WireGuard keys, login state, and network settings all in one file.
+Think of it as a separate "NetBird account" on your machine:
+
+- **Default profile**  
+  Created automatically on first run or after upgrade.  
+- **Custom profiles**  
+  Any number of additional profiles you add yourself (e.g. `work`, `home`, `test`).
+
+Profiles live in your system or user config folders:
+
+| OS     | System-wide path                  | User path                                             |
+| ------ | --------------------------------- | ----------------------------------------------------- |
+| Linux  | `/var/lib/netbird/profiles/...`   | `~/.config/netbird/<profile>.json`                    |
+| macOS  | `/Library/Application Support/...`| `~/Library/Application Support/NetBird/<profile>.json`|
+| Windows| `%ProgramData%\Netbird\profiles\` | `%APPDATA%\Netbird\<profile>.json`                    |
+
+---
+
+## Why Use Profiles?
+
+- **Seamless switching** between multiple NetBird networks/accounts  
+- **No manual config files updates**: all configs are managed through the CLI or GUI
+- **Persistent state**: your last active profile reconnects on startup
+- **Safe defaults**: you cannot remove the active/default profile by accident
+
+---
+
+## Upgrading From an Older Version
+
+If you're upgrading from NetBird below version `0.52.0` that did not support profiles, here's what happens:
+
+* During the first launch after the upgrade, your existing config `/etc/netbird/config.json` (or Windows equivalent) is automatically
+copied to a new profile named  `default`.
+* The `default` profile is set as active, and you can start using it immediately.
+
+---
+
+## Profile CLI Commands
+
+With the CLI, you can manage profiles easily. The main command is:
+
+```bash
+netbird profile <add|list|select|remove> [name]
+````
+
+### Add a New Profile
+
+To create a new profile, use the command:
+
+```bash
+netbird profile add <PROFILE_NAME>
+```
+
+For example, the command below creates a new profile named `work`:
+
+```bash
+netbird profile add work
+```
+
+This command does the following in the background:
+
+* Creates a `work.json` file in your config folder.
+* Keeps the client disconnected until you run `netbird up` or `netbird login`.
+* Will throw an error if the profile with the same name already exists.
+
+### List Profiles
+
+The command below lists all available profiles along with their status:
+
+```bash
+netbird profile list
+```
+
+For example, running this command might output:
+
+```text
+Found 3 profiles:
+✓ work
+✗ default
+✗ home
+```
+
+* **✓** = active
+* **✗** = inactive
+
+### Select (Switch) a Profile
+
+To switch to a specific profile, use:
+
+```bash
+netbird profile select <PROFILE_NAME>
+```
+
+For example, to switch to the `home` profile:
+
+```bash
+netbird profile select home
+```
+
+The successful command will output:
+
+```text
+Profile switched successfully to: home
+```
+
+If `home` hasn't been used before, you will need to run `netbird up` or `netbird login` to authenticate.
+If the profile does not exist, you'll see an error message:
+
+```text
+Error: profile home does not exist
+```
+
+### Remove a Profile
+
+To remove a profile, use:
+
+```bash
+netbird profile remove <PROFILE_NAME>
+```
+
+For example, to remove the `home` profile:
+
+```bash
+netbird profile remove home
+```
+
+If successful, you'll see:
+
+```text
+Profile removed successfully: home
+```
+
+You can't remove an active profile. If the profile your are trying to remove is active, you'll see an error:
+
+```text
+Cannot remove active profile: home
+```
+
+If the profile does not exist, you'll see an error message:
+
+```text
+Error: profile home does not exist
+```
+
+The command does the following in the background:
+
+* Removes `home.json` and `home.state.json` files from your config folder.
+
+---
+
+### Using `--profile` Flags
+
+You can use the `--profile` flag with any NetBird CLI command to specify which profile to use for that command.
+This is useful for running commands in a specific context without switching profiles manually.
+
+```bash
+netbird up --profile work
+netbird login --profile home
+```
+
+NetBird switches to the named profile then runs the command under the hood. If the profile is new and hasn't been used yet,
+you'll be prompted to authenticate.