diff --git a/yazi-plugin/src/isolate/preload.rs b/yazi-plugin/src/isolate/preload.rs
index 2080c41f..e28fd813 100644
--- a/yazi-plugin/src/isolate/preload.rs
+++ b/yazi-plugin/src/isolate/preload.rs
@@ -5,7 +5,7 @@ use yazi_dds::Sendable;
 use yazi_shared::event::Cmd;
 
 use super::slim_lua;
-use crate::{Error, deprecate, elements::Rect, file::File, loader::LOADER};
+use crate::{Error, elements::Rect, file::File, loader::LOADER};
 
 pub async fn preload(
 	cmd: &'static Cmd,
@@ -35,7 +35,7 @@ pub async fn preload(
 		let ok = match ok {
 			Value::Boolean(b) => b,
 			Value::Integer(n) => {
-				deprecate!(lua, "The integer return value of `preload()` has been deprecated since 25.01.27, please use the new `(bool, error)` instead, in your {}.
+				crate::deprecate!(lua, "The integer return value of `preload()` has been deprecated since 25.01.27, please use the new `(bool, error)` instead, in your {}.
 
 See #2253 for more information: https://github.com/sxyazi/yazi/pull/2253");
 				if n as u8 & 1 == 0 {
diff --git a/yazi-plugin/src/macros.rs b/yazi-plugin/src/macros.rs
index 7a3499da..416ea571 100644
--- a/yazi-plugin/src/macros.rs
+++ b/yazi-plugin/src/macros.rs
@@ -124,18 +124,10 @@ macro_rules! impl_file_methods {
 #[macro_export]
 macro_rules! deprecate {
 	($lua:ident, $tt:tt) => {{
-		static WARNED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
-		if !WARNED.swap(true, std::sync::atomic::Ordering::Relaxed) {
-			let id = match $lua.named_registry_value::<$crate::RtRef>("rt")?.current() {
-				Some(id) => &format!("`{id}.yazi` plugin"),
-				None => "`init.lua` config",
-			};
-			yazi_proxy::AppProxy::notify(yazi_proxy::options::NotifyOpt {
-				title:   "Deprecated API".to_owned(),
-				content: format!($tt, id),
-				level:   yazi_proxy::options::NotifyLevel::Warn,
-				timeout: std::time::Duration::from_secs(20),
-			});
-		}
+		let id = match $lua.named_registry_value::<$crate::RtRef>("rt")?.current() {
+			Some(id) => &format!("`{id}.yazi` plugin"),
+			None => "`init.lua` config",
+		};
+		yazi_proxy::deprecate!(format!($tt, id));
 	}};
 }
diff --git a/yazi-proxy/src/lib.rs b/yazi-proxy/src/lib.rs
index 5a565072..cbe1f660 100644
--- a/yazi-proxy/src/lib.rs
+++ b/yazi-proxy/src/lib.rs
@@ -1,3 +1,5 @@
+mod macros;
+
 yazi_macro::mod_pub!(options);
 
 yazi_macro::mod_flat!(app completion confirm input manager pick semaphore tab tasks);
diff --git a/yazi-proxy/src/macros.rs b/yazi-proxy/src/macros.rs
new file mode 100644
index 00000000..c94c5719
--- /dev/null
+++ b/yazi-proxy/src/macros.rs
@@ -0,0 +1,14 @@
+#[macro_export]
+macro_rules! deprecate {
+	($content:expr) => {{
+		static WARNED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
+		if !WARNED.swap(true, std::sync::atomic::Ordering::Relaxed) {
+			$crate::AppProxy::notify($crate::options::NotifyOpt {
+				title:   "Deprecated API".to_owned(),
+				content: $content.to_owned(),
+				level:   $crate::options::NotifyLevel::Warn,
+				timeout: std::time::Duration::from_secs(20),
+			});
+		}
+	}};
+}
diff --git a/yazi-proxy/src/options/plugin.rs b/yazi-proxy/src/options/plugin.rs
index 2d84d467..eb1c81c6 100644
--- a/yazi-proxy/src/options/plugin.rs
+++ b/yazi-proxy/src/options/plugin.rs
@@ -26,7 +26,16 @@ impl TryFrom<CmdCow> for PluginOpt {
 			bail!("plugin id cannot be empty");
 		};
 
-		let args = if let Some(s) = c.str("args") {
+		let args = if let Some(s) = c.second_str() {
+			Cmd::parse_args(yazi_shared::shell::split_unix(s)?.into_iter(), true)?
+		} else if let Some(s) = c.str("args") {
+			crate::deprecate!(
+				format!("The `args` parameter of the `plugin` command has been deprecated. Please use the second positional argument of `plugin` instead.
+
+For example, replace `plugin test --args=foobar` with `plugin test foobar`, for your `plugin {}` command.
+
+See #2299 for more information: https://github.com/sxyazi/yazi/pull/2299", id)
+			);
 			Cmd::parse_args(yazi_shared::shell::split_unix(s)?.into_iter(), true)?
 		} else {
 			Default::default()
diff --git a/yazi-proxy/src/options/search.rs b/yazi-proxy/src/options/search.rs
index 7f24f832..03e82c42 100644
--- a/yazi-proxy/src/options/search.rs
+++ b/yazi-proxy/src/options/search.rs
@@ -23,6 +23,7 @@ impl TryFrom<CmdCow> for SearchOpt {
 		Ok(Self {
 			via,
 			subject,
+			// TODO: use second positional argument instead of `args` parameter
 			args: yazi_shared::shell::split_unix(c.str("args").unwrap_or_default()).map_err(|_| ())?,
 			args_raw: c.take_str("args").unwrap_or_default(),
 		})
diff --git a/yazi-proxy/src/tab.rs b/yazi-proxy/src/tab.rs
index 210ed663..9e48fc4b 100644
--- a/yazi-proxy/src/tab.rs
+++ b/yazi-proxy/src/tab.rs
@@ -24,6 +24,7 @@ impl TabProxy {
 	#[inline]
 	pub fn search_do(opt: SearchOpt) {
 		emit!(Call(
+			// TODO: use second positional argument instead of `args` parameter
 			Cmd::args("search_do", &[opt.subject]).with("via", opt.via).with("args", opt.args_raw),
 			Layer::Manager
 		));
diff --git a/yazi-shared/src/event/cmd.rs b/yazi-shared/src/event/cmd.rs
index c5f7b916..deec531a 100644
--- a/yazi-shared/src/event/cmd.rs
+++ b/yazi-shared/src/event/cmd.rs
@@ -78,6 +78,12 @@ impl Cmd {
 	#[inline]
 	pub fn first_str(&self) -> Option<&str> { self.str(0) }
 
+	#[inline]
+	pub fn second(&self) -> Option<&Data> { self.get(1) }
+
+	#[inline]
+	pub fn second_str(&self) -> Option<&str> { self.str(1) }
+
 	// --- Take
 	#[inline]
 	pub fn take(&mut self, name: impl Into<DataKey>) -> Option<Data> {