diff --git a/core/commands/pin/pin.go b/core/commands/pin/pin.go
index b27b1e2bf94..b87760aaff4 100644
--- a/core/commands/pin/pin.go
+++ b/core/commands/pin/pin.go
@@ -359,10 +359,10 @@ Example:
 	},
 	Options: []cmds.Option{
 		cmds.StringOption(pinTypeOptionName, "t", "The type of pinned keys to list. Can be \"direct\", \"indirect\", \"recursive\", or \"all\".").WithDefault("all"),
-		cmds.BoolOption(pinQuietOptionName, "q", "Write just hashes of objects."),
+		cmds.BoolOption(pinQuietOptionName, "q", "Output only the CIDs of pins."),
+		cmds.StringOption(pinNameOptionName, "n", "Limit returned pins to ones with names that contain the value provided (case-sensitive, partial match). Implies --names=true."),
 		cmds.BoolOption(pinStreamOptionName, "s", "Enable streaming of pins as they are discovered."),
-		cmds.BoolOption(pinNamesOptionName, "n", "Enable displaying pin names (slower)."),
-		cmds.StringOption(pinNameOptionName, "Display pins with names that contain the value provided (case-sensitive, partial match)."),
+		cmds.BoolOption(pinNamesOptionName, "Include pin names in the output (slower, disabled by default)."),
 	},
 	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
 		api, err := cmdenv.GetApi(env, req)
diff --git a/docs/changelogs/v0.29.md b/docs/changelogs/v0.29.md
index 632c47b15bb..a7c6f260872 100644
--- a/docs/changelogs/v0.29.md
+++ b/docs/changelogs/v0.29.md
@@ -17,7 +17,12 @@
 
 #### Add search functionality for pin names
 
-It is now possible to search for pins by name. To do so, use `ipfs pin ls --name "SomeName"`. The search is case-sensitive and will return all pins having a name which contains the exact word provided.
+It is now possible to search for pins by name via `ipfs pin ls --name "SomeName"`.
+The search is case-sensitive and will return all pins that contain the specified substring in their name.
+
+> [!TIP]
+> The `ipfs pin ls -n` is now a shorthand for `ipfs pin ls --name`, mirroring the behavior of `ipfs pin add`.
+> See `ipfs pin ls --help` for more information.
 
 #### Customizing `ipfs add` defaults
 
@@ -27,7 +32,7 @@ The hash function, CID version, or UnixFS raw leaves and chunker behaviors can b
 > [!TIP]
 > As a convenience, two CID [profiles](../config.md#profile) are provided: `legacy-cid-v0` and `test-cid-v1`.
 > A test profile that defaults to modern CIDv1 can be applied via `ipfs config profile apply test-cid-v1`.
-> We encourage users to try it and report any issues.
+> We encourage users to try it and report any issues in [kubo#4143](https://github.com/ipfs/kubo/issues/4143).
 
 ### 📝 Changelog
 
diff --git a/test/cli/pins_test.go b/test/cli/pins_test.go
index 88da250b155..3e3325a019e 100644
--- a/test/cli/pins_test.go
+++ b/test/cli/pins_test.go
@@ -242,7 +242,7 @@ func TestPins(t *testing.T) {
 		require.NotContains(t, lsOut, outADetailed)
 	})
 
-	t.Run("test listing pins which contains specific name", func(t *testing.T) {
+	t.Run("test listing pins with names that contain specific string", func(t *testing.T) {
 		t.Parallel()
 
 		node := harness.NewT(t).NewNode().Init()
@@ -254,27 +254,30 @@ func TestPins(t *testing.T) {
 		outB := cidBStr + " recursive testPin"
 		outC := cidCStr + " recursive randPin"
 
-		_ = node.IPFS("pin", "add", "--name", "testPin", cidAStr)
-		lsOut := pinLs(node, "-t=recursive", "--name=test")
-		require.Contains(t, lsOut, outA)
-		lsOut = pinLs(node, "-t=recursive", "--name=randomLabel")
-		require.NotContains(t, lsOut, outA)
-
-		_ = node.IPFS("pin", "add", "--name", "testPin", cidBStr)
-		lsOut = pinLs(node, "-t=recursive", "--name=test")
-		require.Contains(t, lsOut, outA)
-		require.Contains(t, lsOut, outB)
-
-		_ = node.IPFS("pin", "add", "--name", "randPin", cidCStr)
-		lsOut = pinLs(node, "-t=recursive", "--name=rand")
-		require.NotContains(t, lsOut, outA)
-		require.NotContains(t, lsOut, outB)
-		require.Contains(t, lsOut, outC)
-
-		lsOut = pinLs(node, "-t=recursive", "--name=testPin")
-		require.Contains(t, lsOut, outA)
-		require.Contains(t, lsOut, outB)
-		require.NotContains(t, lsOut, outC)
+		// make sure both -n and --name work
+		for _, nameParam := range []string{"--name", "-n"} {
+			_ = node.IPFS("pin", "add", "--name", "testPin", cidAStr)
+			lsOut := pinLs(node, "-t=recursive", nameParam+"=test")
+			require.Contains(t, lsOut, outA)
+			lsOut = pinLs(node, "-t=recursive", nameParam+"=randomLabel")
+			require.NotContains(t, lsOut, outA)
+
+			_ = node.IPFS("pin", "add", "--name", "testPin", cidBStr)
+			lsOut = pinLs(node, "-t=recursive", nameParam+"=test")
+			require.Contains(t, lsOut, outA)
+			require.Contains(t, lsOut, outB)
+
+			_ = node.IPFS("pin", "add", "--name", "randPin", cidCStr)
+			lsOut = pinLs(node, "-t=recursive", nameParam+"=rand")
+			require.NotContains(t, lsOut, outA)
+			require.NotContains(t, lsOut, outB)
+			require.Contains(t, lsOut, outC)
+
+			lsOut = pinLs(node, "-t=recursive", nameParam+"=testPin")
+			require.Contains(t, lsOut, outA)
+			require.Contains(t, lsOut, outB)
+			require.NotContains(t, lsOut, outC)
+		}
 	})
 
 	t.Run("test overwriting pin with name", func(t *testing.T) {