From f50384741a482e0192e351d66e65b3fe56d683e4 Mon Sep 17 00:00:00 2001 From: "Theodor S. Midtlien" Date: Mon, 8 Jun 2026 15:54:53 +0200 Subject: [PATCH 1/5] Add profile id migration --- src/pages/client/profiles.mdx | 124 ++++++++++++++++++++++++++-------- src/pages/get-started/cli.mdx | 8 +-- 2 files changed, 98 insertions(+), 34 deletions(-) diff --git a/src/pages/client/profiles.mdx b/src/pages/client/profiles.mdx index c2432938c..3ce65c18c 100644 --- a/src/pages/client/profiles.mdx +++ b/src/pages/client/profiles.mdx @@ -32,7 +32,8 @@ if needed. ## Manage Profiles in the GUI -* **Add** a new profile with a friendly name input. +* **Add** a new profile with a friendly name input. Names need not be unique — each + profile is tracked by its own generated ID. * **Delete** any inactive profile (trash icon). * **Active and default** profiles cannot be removed. @@ -50,7 +51,20 @@ Think of it as a separate "NetBird account" on your machine: - **Custom profiles** Any number of additional profiles you add yourself (e.g. `work`, `home`, `test`). -Profiles live in your system or user config folders: +### Names and IDs + +Each profile has two parts: + +- A **name**: the free-form, human-readable label you choose (e.g. `work`). Names are + for display only and **do not have to be unique**: you can have two profiles both named + `work`. +- An **ID**: a unique identifier generated automatically when the profile is created. The + ID is also the profile's on-disk filename (`.json`). The CLI shows a short, 8-character + form of the ID, which is enough to identify and select a profile. + +The `default` profile is special: its ID is simply `default`. + +Profiles live in your system or user config folders, stored as `.json`: | OS | Config path | | ------ | --------------------------------- | @@ -116,9 +130,15 @@ When profiles are disabled: With the CLI, you can manage profiles easily. The main command is: ```bash -netbird profile [name] +netbird profile [name|id] ```` + + `select` and `remove` accept a profile **handle**: an exact ID, a unique ID prefix, or a + unique name. `add` takes a free-form name. See [Names and IDs](#names-and-ids) for the + distinction between a profile's name and its ID. + + ### Add a New Profile To create a new profile, use the command: @@ -133,11 +153,25 @@ For example, the command below creates a new profile named `work`: netbird profile add work ``` +On success it prints the new profile's short ID alongside the name: + +```text +Profile added: a1b2c3d4 work +``` + This command does the following in the background: -* Creates a `work.json` file in your config folder. +* Generates a unique ID and creates an `.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. + +Profile names do not have to be unique. If another profile already uses the same name, the +new profile is still created (with its own ID) and a warning is printed: + +```text +Warning: 1 other profile(s) already use the name "work". +Use `netbird profile list --show-id` to disambiguate later. +Profile added: e5f6a7b8 work +``` ### List Profiles @@ -150,40 +184,65 @@ netbird profile list For example, running this command might output: ```text -Found 3 profiles: -✓ work -✗ default -✗ home +NAME ACTIVE +work ✓ +default +home +``` + +A **✓** in the `ACTIVE` column marks the active profile; inactive profiles are left blank. + +To also show each profile's short ID, add the `--show-id` flag: + +```bash +netbird profile list --show-id +``` + +```text +ID NAME ACTIVE +a1b2c3d4 work ✓ +default default +e5f6a7b8 home ``` -* **✓** = active -* **✗** = inactive +This is useful when several profiles share the same name — the ID column lets you tell them +apart and select or remove the right one by its ID prefix. ### Select (Switch) a Profile To switch to a specific profile, use: ```bash -netbird profile select +netbird profile select ``` -For example, to switch to the `home` profile: +The handle can be the profile's name, its full ID, or a unique ID prefix: ```bash -netbird profile select home +netbird profile select home # by name +netbird profile select e5f6a7b8 # by ID prefix ``` -The successful command will output: +The successful command will output the short ID of the now-active profile: ```text -Profile switched successfully to: home +Profile switched to: e5f6a7b8 ``` -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: +If the profile hasn't been used before, you will need to run `netbird up` or `netbird login` to authenticate. +If the handle matches no profile, you'll see: ```text -Error: profile home does not exist +Error: profile "home" not found +``` + +If the handle is ambiguous (for example, a name shared by multiple profiles), the command +lists the candidates and tells you how to disambiguate: + +```text +Error: name "work" is ambiguous (2 profiles share this name) +Run `netbird profile list --show-id` to see IDs, then select by ID prefix: + netbird profile select|remove ``` ### Remove a Profile @@ -191,36 +250,40 @@ Error: profile home does not exist To remove a profile, use: ```bash -netbird profile remove +netbird profile remove ``` -For example, to remove the `home` profile: +Like `select`, the handle can be a name, a full ID, or a unique ID prefix: ```bash netbird profile remove home ``` -If successful, you'll see: +If successful, the full ID of the removed profile is printed so you can confirm exactly which +profile a name or prefix resolved to: ```text -Profile removed successfully: home +Profile removed: e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 ``` -You can't remove an active profile. If the profile your are trying to remove is active, you'll see an error: +You can't remove an active profile. If the profile you are trying to remove is active, you'll see an error: ```text -Cannot remove active profile: home +Cannot remove active profile: e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 ``` -If the profile does not exist, you'll see an error message: +If the handle matches no profile, you'll see: ```text -Error: profile home does not exist +Error: profile "home" not found ``` +Ambiguous handles are handled the same way as for `select`, the command lists the candidates +and points you at `--show-id`. + The command does the following in the background: -* Removes `home.json` and `home.state.json` files from your config folder. +* Removes the profile's `.json` and `.state.json` files from your config folder. --- @@ -234,5 +297,6 @@ 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. +The value is resolved as a handle (name, full ID, or unique ID prefix), the same way as +`profile select`. NetBird switches to the resolved 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. diff --git a/src/pages/get-started/cli.mdx b/src/pages/get-started/cli.mdx index a67e40c51..8a1f3fa3d 100644 --- a/src/pages/get-started/cli.mdx +++ b/src/pages/get-started/cli.mdx @@ -628,10 +628,10 @@ netbird profile [command] ``` #### Subcommands -- `list`: List all profiles. -- `add`: Add a new profile. -- `remove`: Remove a profile. -- `select`: Select a profile to use. +- `list`: List all profiles. Add `--show-id` to include each profile's ID column. +- `add`: Add a new profile by name. Names need not be unique; a unique ID is generated per profile. +- `remove`: Remove a profile by name, ID, or unique ID prefix. +- `select`: Select a profile to use by name, ID, or unique ID prefix. ### version Outputs the `netbird` command version. From 0eb0bd1e792bd403901b0f4b1e5c48941f58b811 Mon Sep 17 00:00:00 2001 From: "Theodor S. Midtlien" Date: Tue, 9 Jun 2026 11:13:25 +0200 Subject: [PATCH 2/5] Update handle --- src/pages/client/profiles.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/client/profiles.mdx b/src/pages/client/profiles.mdx index 3ce65c18c..8d404700d 100644 --- a/src/pages/client/profiles.mdx +++ b/src/pages/client/profiles.mdx @@ -130,7 +130,7 @@ When profiles are disabled: With the CLI, you can manage profiles easily. The main command is: ```bash -netbird profile [name|id] +netbird profile [name|handle] ```` @@ -213,7 +213,7 @@ apart and select or remove the right one by its ID prefix. To switch to a specific profile, use: ```bash -netbird profile select +netbird profile select ``` The handle can be the profile's name, its full ID, or a unique ID prefix: @@ -250,7 +250,7 @@ Run `netbird profile list --show-id` to see IDs, then select by ID prefix: To remove a profile, use: ```bash -netbird profile remove +netbird profile remove ``` Like `select`, the handle can be a name, a full ID, or a unique ID prefix: From 00ce7199aaf5aa8c01f35062b170b16b984b7c6a Mon Sep 17 00:00:00 2001 From: "Theodor S. Midtlien" Date: Fri, 12 Jun 2026 11:00:36 +0200 Subject: [PATCH 3/5] Add rename profile --- src/pages/client/profiles.mdx | 48 +++++++++++++++++++++++++++++++---- src/pages/get-started/cli.mdx | 1 + 2 files changed, 44 insertions(+), 5 deletions(-) diff --git a/src/pages/client/profiles.mdx b/src/pages/client/profiles.mdx index 8d404700d..e56a53f1f 100644 --- a/src/pages/client/profiles.mdx +++ b/src/pages/client/profiles.mdx @@ -62,7 +62,8 @@ Each profile has two parts: ID is also the profile's on-disk filename (`.json`). The CLI shows a short, 8-character form of the ID, which is enough to identify and select a profile. -The `default` profile is special: its ID is simply `default`. +The `default` profile is special: its ID is always `default`. You can rename its display label, +but it keeps that reserved ID and cannot be removed. Profiles live in your system or user config folders, stored as `.json`: @@ -130,13 +131,13 @@ When profiles are disabled: With the CLI, you can manage profiles easily. The main command is: ```bash -netbird profile [name|handle] +netbird profile [name|handle] ```` - `select` and `remove` accept a profile **handle**: an exact ID, a unique ID prefix, or a - unique name. `add` takes a free-form name. See [Names and IDs](#names-and-ids) for the - distinction between a profile's name and its ID. + `select`, `rename`, and `remove` accept a profile **handle**: an exact ID, a unique ID + prefix, or a unique name. `add` takes a free-form name. See [Names and IDs](#names-and-ids) + for the distinction between a profile's name and its ID. ### Add a New Profile @@ -173,6 +174,37 @@ Use `netbird profile list --show-id` to disambiguate later. Profile added: e5f6a7b8 work ``` +### Rename a Profile + +You can change a profile's display name at any time without affecting its ID, config, or login +state. The profile's `.json` file stays the same, only the name stored inside it changes. + +```bash +netbird profile rename +``` + +The handle can be the profile's current name, its full ID, or a unique ID prefix. For example, +to rename the `work` profile to `office`: + +```bash +netbird profile rename work office +``` + +On success: + +```text +Profile renamed from work to office +``` + +A few things to note: + +* The new name is free-form and **does not have to be unique**. If another profile already uses + it, the rename still succeeds and a warning is printed (same as `add`). +* The **default profile can be renamed**. Its label changes everywhere it's shown, but it keeps + its reserved `default` ID and still cannot be removed. +* If the handle is ambiguous or matches no profile, you'll get the same errors as `select` and + `remove` (see below), pointing you at `--show-id`. + ### List Profiles The command below lists all available profiles along with their status: @@ -272,6 +304,12 @@ You can't remove an active profile. If the profile you are trying to remove is a Cannot remove active profile: e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 ``` +The **default profile cannot be removed** either (though it can be renamed): + +```text +cannot remove default profile with name: default +``` + If the handle matches no profile, you'll see: ```text diff --git a/src/pages/get-started/cli.mdx b/src/pages/get-started/cli.mdx index 8a1f3fa3d..2129ba73d 100644 --- a/src/pages/get-started/cli.mdx +++ b/src/pages/get-started/cli.mdx @@ -630,6 +630,7 @@ netbird profile [command] #### Subcommands - `list`: List all profiles. Add `--show-id` to include each profile's ID column. - `add`: Add a new profile by name. Names need not be unique; a unique ID is generated per profile. +- `rename`: Rename a profile (by name, ID, or unique ID prefix) to a new free-form name. The default profile can be renamed. - `remove`: Remove a profile by name, ID, or unique ID prefix. - `select`: Select a profile to use by name, ID, or unique ID prefix. From 9c20fb891e7bfafafef8692c0fc4f604b994a378 Mon Sep 17 00:00:00 2001 From: "Theodor S. Midtlien" Date: Tue, 16 Jun 2026 20:07:10 +0200 Subject: [PATCH 4/5] Small fix --- src/pages/client/profiles.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/pages/client/profiles.mdx b/src/pages/client/profiles.mdx index e56a53f1f..af6134b85 100644 --- a/src/pages/client/profiles.mdx +++ b/src/pages/client/profiles.mdx @@ -32,8 +32,7 @@ if needed. ## Manage Profiles in the GUI -* **Add** a new profile with a friendly name input. Names need not be unique — each - profile is tracked by its own generated ID. +* **Add** a new profile with a friendly name input. Names need not be unique, each profile is tracked by its own generated ID. * **Delete** any inactive profile (trash icon). * **Active and default** profiles cannot be removed. @@ -237,7 +236,7 @@ default default e5f6a7b8 home ``` -This is useful when several profiles share the same name — the ID column lets you tell them +This is useful when several profiles share the same name. The ID column lets you tell them apart and select or remove the right one by its ID prefix. ### Select (Switch) a Profile From 31e8c77d88bd926dfce990e2aca28fdcf0e55379 Mon Sep 17 00:00:00 2001 From: "Theodor S. Midtlien" Date: Wed, 17 Jun 2026 13:16:28 +0200 Subject: [PATCH 5/5] Add order of preference for profiles --- src/pages/client/profiles.mdx | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/src/pages/client/profiles.mdx b/src/pages/client/profiles.mdx index af6134b85..a6ff8473f 100644 --- a/src/pages/client/profiles.mdx +++ b/src/pages/client/profiles.mdx @@ -134,9 +134,9 @@ netbird profile [name|handle] ```` - `select`, `rename`, and `remove` accept a profile **handle**: an exact ID, a unique ID - prefix, or a unique name. `add` takes a free-form name. See [Names and IDs](#names-and-ids) - for the distinction between a profile's name and its ID. + `select`, `rename`, and `remove` accept a profile **handle** (in order of precedence): + an exact ID, a unique name or a unique ID prefix. `add` takes a free-form name. + See [Names and IDs](#names-and-ids) for the distinction between a profile's name and its ID. ### Add a New Profile @@ -247,7 +247,7 @@ To switch to a specific profile, use: netbird profile select ``` -The handle can be the profile's name, its full ID, or a unique ID prefix: +The handle can be the full ID, profile's name, or a unique ID prefix: ```bash netbird profile select home # by name @@ -267,8 +267,7 @@ If the handle matches no profile, you'll see: Error: profile "home" not found ``` -If the handle is ambiguous (for example, a name shared by multiple profiles), the command -lists the candidates and tells you how to disambiguate: +If the handle is ambiguous (for example, a name shared by multiple profiles), the command lists the candidates and tells you how to disambiguate: ```text Error: name "work" is ambiguous (2 profiles share this name) @@ -315,8 +314,7 @@ If the handle matches no profile, you'll see: Error: profile "home" not found ``` -Ambiguous handles are handled the same way as for `select`, the command lists the candidates -and points you at `--show-id`. +If the handle matches multiple profiles, none is removed and the command points you at `--show-id` (same way as for `select`). The command does the following in the background: