enhance: differentiate permalink rename and file movement of mv cli

Author: virtualguard101

docs/usage/cli.md

@@ -1,5 +1,5 @@
 ---
-date: 2026-01-10 22:09:00
+date: 2026-01-10 23:40:00
 title: Command Line Interface
 permalink: 
 publish: true
@@ -131,7 +131,13 @@ Remove a note file and its corresponding asset directory.
 
 ### `move`
 
-Move or rename a note file/directory and its corresponding asset directory.
+Move or rename a note file/directory and its corresponding asset directory, or rename permalink value.
+
+The `move` command supports two modes:
+
+#### File Move Mode (default)
+
+Move or rename a note file/directory and its corresponding asset directory. The permalink value remains unchanged, and asset directories are moved based on their permalink.
 
 - **Usage:**
 
@@ -144,18 +150,24 @@ Move or rename a note file/directory and its corresponding asset directory.
 
     - `SOURCE` (required): Current path of the note file or directory
 
-    - `DESTINATION` (required): Destination path
+    - `DESTINATION` (required): Destination path (or parent directory if exists)
 
 - **Options:**
 
-    - `--keep-source-assets`: Keep the source asset directory (don't move it)
+    - `--keep-source-assets`: Keep the source asset directory (don't move it) [NOT IMPLEMENTED]
 
     - `--yes, -y`: Skip confirmation prompt
 
 - **Features:**
 
     - Moves both the note file and its corresponding asset directory by default
 
+    - Asset directories are identified by permalink, not filename
+
+    - If moving to a different directory, asset directory moves with the note
+
+    - If only renaming the file within the same directory, asset directory stays in place (based on permalink)
+
     - Supports moving single files or entire directories
 
     - Automatically creates necessary parent directories
@@ -171,17 +183,14 @@ Move or rename a note file/directory and its corresponding asset directory.
 - **Examples:**
 
     ```bash
-    # Rename a note
+    # Rename a note file (same directory, asset directory stays in place)
     mkdocs-note move docs/notes/old-name.md docs/notes/new-name.md
 
-    # Move to different directory
+    # Move to different directory (asset directory moves with note)
     mkdocs-note mv docs/notes/draft.md docs/notes/published/
 
     # Move entire directory
     mkdocs-note move docs/notes/drafts docs/notes/published --yes
-
-    # Move without moving assets
-    mkdocs-note mv docs/notes/test.md docs/archive/test.md --keep-source-assets
     ```
 
 - **Output:**
@@ -193,6 +202,60 @@ Move or rename a note file/directory and its corresponding asset directory.
     📁 Assets moved
     ```
 
+#### Permalink Rename Mode
+
+Rename the permalink value in frontmatter and the asset directory name. The file location remains unchanged.
+
+- **Usage:**
+
+    ```bash
+    mkdocs-note move SOURCE -p PERMALINK [OPTIONS]
+    mkdocs-note mv SOURCE --permalink PERMALINK [OPTIONS]  # Alias
+    ```
+
+- **Arguments:**
+
+    - `SOURCE` (required): Path to the note file (must be a file, not a directory)
+
+    - `DESTINATION`: Ignored in permalink rename mode
+
+- **Options:**
+
+    - `--permalink, -p` (required): New permalink value
+
+    - `--yes, -y`: Skip confirmation prompt
+
+- **Features:**
+
+    - Updates the permalink value in the note file's frontmatter
+
+    - Renames the asset directory based on the new permalink value
+
+    - File location remains unchanged
+
+    - Only works on single files, not directories
+
+    - Prompts for confirmation before renaming (unless `--yes` is used)
+
+- **Examples:**
+
+    ```bash
+    # Rename permalink and asset directory
+    mkdocs-note move docs/notes/my-note.md -p new-permalink-slug
+
+    # Rename permalink without confirmation
+    mkdocs-note mv docs/notes/test.md --permalink updated-slug --yes
+    ```
+
+- **Output:**
+
+    ```
+    ✅ Successfully renamed permalink
+    📝 File: docs/notes/my-note.md
+    🔗 Permalink: old-permalink → new-permalink-slug
+    📁 Asset directory renamed
+    ```
+
 ### `clean`
 
 Clean up orphaned asset directories without corresponding notes.

src/mkdocs_note/cli.py

@@ -279,11 +279,16 @@ def rm_command(ctx, file_path, keep_assets, yes):
 
 @cli.command("move")
 @click.argument("source", required=True)
-@click.argument("destination", required=True)
+@click.argument("destination", required=False)
+@click.option(
+	"--permalink",
+	"-p",
+	help="Rename permalink value and asset directory name (destination argument is ignored in this mode)",
+)
 @click.option(
 	"--keep-source-assets",
 	is_flag=True,
-	help="Keep the source asset directory (don't move it)",
+	help="Keep the source asset directory (don't move it) [NOT IMPLEMENTED]",
 )
 @click.option(
 	"--yes",
@@ -292,60 +297,151 @@ def rm_command(ctx, file_path, keep_assets, yes):
 	help="Skip confirmation prompt",
 )
 @click.pass_context
-def move_command(ctx, source, destination, keep_source_assets, yes):
-	"""Move or rename a note file/directory and its asset directory.
+def move_command(ctx, source, destination, permalink, keep_source_assets, yes):
+	"""Move or rename a note file/directory and its asset directory, or rename permalink.
 
 	\b
 	Aliases: mv
 
+	\b
+	File Move Mode (default):
+	    Move or rename a note file/directory and its asset directory.
+
 	\b
 	Examples:
+	    # Move/rename file
 	    mkdocs-note move docs/notes/old.md docs/notes/new.md
 	    mkdocs-note mv docs/notes/test.md docs/notes/archive
+
+	    # Move entire directory
 	    mkdocs-note move docs/notes/drafts docs/notes/published --yes
 
+	\b
+	Permalink Rename Mode (use -p/--permalink):
+	    Rename permalink value in frontmatter and asset directory name.
+
+	\b
+	Examples:
+	    mkdocs-note move docs/notes/my-note.md -p new-permalink
+	    mkdocs-note mv docs/notes/test.md --permalink updated-slug
+
 	\b
 	Arguments:
-	    SOURCE: Current path of the note file or directory
-	    DESTINATION: Destination path (or parent directory if exists)
+	    SOURCE: Current path of the note file or directory (or file path for permalink mode)
+	    DESTINATION: Destination path (or parent directory if exists). Ignored if --permalink is used.
 	"""
 	try:
 		# Load configuration and setup environment
 		config = MkdocsNoteConfig()
 		setup_cli_environment(config)
 
 		source_path = Path(source)
-		dest_path = Path(destination)
 
 		# Check if source exists
 		if not source_path.exists():
 			click.echo(f"❌ Error: Source does not exist: {source_path}", err=True)
 			sys.exit(1)
 
-		# Confirmation prompt (unless --yes)
-		if not yes:
-			asset_msg = "with assets" if not keep_source_assets else "(keeping assets)"
-			if not click.confirm(f"Move {source_path} → {dest_path} {asset_msg}?"):
-				click.echo("⚠️  Cancelled")
-				sys.exit(0)
-
-		# Move the note using MoveCommand
-		# Note: Current MoveCommand doesn't have keep_source_assets parameter
-		# It always moves assets, so we need to handle this limitation
-		command = MoveCommand()
-		command.execute(source_path, dest_path)
-
-		# Check if move was successful
-		if dest_path.exists() and not source_path.exists():
-			click.echo("✅ Successfully moved")
-			click.echo(f"📝 From: {source_path}")
-			click.echo(f"📝 To: {dest_path}")
-			if not keep_source_assets:
-				click.echo("📁 Assets moved")
-			else:
-				click.echo("📁 Assets kept at source")
+		# Permalink rename mode
+		if permalink:
+			if not source_path.is_file():
+				click.echo(
+					f"❌ Error: Permalink rename only works on files, not directories: {source_path}",
+					err=True,
+				)
+				sys.exit(1)
+
+			# Get current permalink for confirmation message
+			current_permalink = cli_common.get_permalink_from_file(source_path)
+
+			# Confirmation prompt (unless --yes)
+			if not yes:
+				current_msg = (
+					f"'{current_permalink}'" if current_permalink else "(none)"
+				)
+				if not click.confirm(
+					f"Rename permalink in {source_path} from {current_msg} to '{permalink}'?"
+				):
+					click.echo("⚠️  Cancelled")
+					sys.exit(0)
+
+			# Rename permalink using MoveCommand
+			command = MoveCommand()
+			command.execute(source_path, destination=None, permalink=permalink)
+
+			click.echo("✅ Successfully renamed permalink")
+			click.echo(f"📝 File: {source_path}")
+			click.echo(f"🔗 Permalink: {current_permalink or '(none)'} → {permalink}")
+			click.echo("📁 Asset directory renamed")
 			sys.exit(0)
+
+		# File move mode (original behavior)
 		else:
+			if destination is None:
+				click.echo(
+					"❌ Error: DESTINATION is required in file move mode", err=True
+				)
+				sys.exit(1)
+
+			dest_path = Path(destination)
+
+			# Confirmation prompt (unless --yes)
+			if not yes:
+				asset_msg = (
+					"with assets" if not keep_source_assets else "(keeping assets)"
+				)
+				if not click.confirm(f"Move {source_path} → {dest_path} {asset_msg}?"):
+					click.echo("⚠️  Cancelled")
+					sys.exit(0)
+
+			# Save source type before move (since source_path won't exist after move)
+			is_source_file = source_path.is_file()
+			is_source_dir = source_path.is_dir()
+			source_name = source_path.name
+
+			# Move the note using MoveCommand
+			# Note: Current MoveCommand doesn't have keep_source_assets parameter
+			# It always moves assets, so we need to handle this limitation
+			command = MoveCommand()
+			command.execute(source_path, dest_path)
+
+			# Check if move was successful
+			# For directory destinations, check if file exists in destination
+			if is_source_file:
+				# Determine final destination path
+				if dest_path.exists() and dest_path.is_dir():
+					# File moved into directory
+					final_dest = dest_path / source_name
+				else:
+					# File moved/renamed to dest_path
+					final_dest = dest_path
+
+				# Check if move was successful
+				if final_dest.exists() and not source_path.exists():
+					click.echo("✅ Successfully moved")
+					click.echo(f"📝 From: {source_path}")
+					click.echo(f"📝 To: {final_dest}")
+					if not keep_source_assets:
+						click.echo("📁 Assets moved")
+					else:
+						click.echo("📁 Assets kept at source")
+					sys.exit(0)
+			elif is_source_dir:
+				# Directory move - check if destination directory exists
+				if (
+					dest_path.exists()
+					and dest_path.is_dir()
+					and not source_path.exists()
+				):
+					click.echo("✅ Successfully moved")
+					click.echo(f"📝 From: {source_path}")
+					click.echo(f"📝 To: {dest_path}")
+					if not keep_source_assets:
+						click.echo("📁 Assets moved")
+					else:
+						click.echo("📁 Assets kept at source")
+					sys.exit(0)
+
 			click.echo("❌ Error: Failed to move note", err=True)
 			sys.exit(1)
 
@@ -356,16 +452,22 @@ def move_command(ctx, source, destination, keep_source_assets, yes):
 
 @cli.command("mv")
 @click.argument("source", required=True)
-@click.argument("destination", required=True)
-@click.option("--keep-source-assets", is_flag=True, help="Keep source assets")
+@click.argument("destination", required=False)
+@click.option(
+	"--permalink", "-p", help="Rename permalink value and asset directory name"
+)
+@click.option(
+	"--keep-source-assets", is_flag=True, help="Keep source assets [NOT IMPLEMENTED]"
+)
 @click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
 @click.pass_context
-def mv_command(ctx, source, destination, keep_source_assets, yes):
+def mv_command(ctx, source, destination, permalink, keep_source_assets, yes):
 	"""Alias for 'move' command - Move or rename a note file/directory and its assets."""
 	ctx.invoke(
 		move_command,
 		source=source,
 		destination=destination,
+		permalink=permalink,
 		keep_source_assets=keep_source_assets,
 		yes=yes,
 	)