diff --git a/Cargo.lock b/Cargo.lock
index 08e4631ac1..3501933ebb 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4945,9 +4945,9 @@ checksum = "daf8dba3b7eb870caf1ddeed7bc9d2a049f3cfdfae7cb521b087cc33ae4c49da"
 
 [[package]]
 name = "usage-lib"
-version = "1.7.3"
+version = "1.7.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e83c65dd7087086e278dc46c7e82c508afed9b9b65099b29476f949331c61f1d"
+checksum = "ab923f719b3048bd1cd2fb738fca978ed2a60756ce15cdad639fc40645adad9c"
 dependencies = [
  "clap",
  "heck 0.5.0",
diff --git a/docs/tasks/task-configuration.md b/docs/tasks/task-configuration.md
index a1d1301156..5dcfa8500c 100644
--- a/docs/tasks/task-configuration.md
+++ b/docs/tasks/task-configuration.md
@@ -254,6 +254,20 @@ like to hide even the output that the task emits, use [`silent`](#silent).
 
 Suppress all output from the task. If set to `"stdout"` or `"stderr"`, only that stream will be suppressed.
 
+### `usage`
+
+- **Type**: `string`
+
+More advanced usage specs can be added to the task's `usage` field. This only applies to toml-tasks.
+
+```toml
+[tasks.test]
+usage = '''
+arg "file" description="The file to test" default="src/main.rs"
+'''
+run = 'cargo test {{arg(name="file")}}'
+```
+
 ## Vars
 
 Vars are variables that can be shared between tasks like environment variables but they are not
diff --git a/docs/tasks/toml-tasks.md b/docs/tasks/toml-tasks.md
index 6423643aef..53fd3c397d 100644
--- a/docs/tasks/toml-tasks.md
+++ b/docs/tasks/toml-tasks.md
@@ -441,3 +441,15 @@ fi
 - `name`: The name of the flag. This is used for help/error messages.
 
 The value will be `true` if the flag is passed, and `false` otherwise.
+
+### Usage spec
+
+More advanced usage specs can be added to the task's `usage` field:
+
+```toml
+[tasks.test]
+usage = '''
+arg "file" description="The file to test" default="src/main.rs"
+'''
+run = 'cargo test {{arg(name="file")}}'
+```
diff --git a/e2e/tasks/test_task_run_toml b/e2e/tasks/test_task_run_toml
index 15c813e994..c0ae7417ab 100644
--- a/e2e/tasks/test_task_run_toml
+++ b/e2e/tasks/test_task_run_toml
@@ -35,3 +35,12 @@ assert "mise run -E windows configtask" "configtask:windows"
 assert "mise run -P windows configtask" "configtask:windows"
 MISE_ENV=windows assert "mise run configtask" "configtask:windows"
 MISE_PROFILE=windows assert "mise run configtask" "configtask:windows"
+
+cat <<EOF >mise.toml
+[tasks.a]
+usage = '''
+arg "myarg" "myarg description" default="foo"
+'''
+run = 'echo {{arg(name="myarg")}}'
+EOF
+assert "mise run a" "foo"
diff --git a/mise.lock b/mise.lock
index a02335be65..1aef9464dc 100644
--- a/mise.lock
+++ b/mise.lock
@@ -15,6 +15,7 @@ backend = "core:bun"
 
 [tools.bun.checksums]
 "bun-darwin-aarch64.zip" = "sha256:64a70fe290bd6391a09d555d4e4e1a8df56543e526bb1381ab344a385348572c"
+"bun-linux-x64-baseline.zip" = "sha256:19584af4189e6434124a556e830427f0f44b7ebed8530eacf4fe369bd14b93d6"
 
 [tools.cargo-binstall]
 version = "1.10.17"
@@ -22,6 +23,7 @@ backend = "aqua:cargo-bins/cargo-binstall"
 
 [tools.cargo-binstall.checksums]
 "cargo-binstall-aarch64-apple-darwin.zip" = "sha256:81abb7de75ef130844bb58965bdb93969afadd0821cf5e1e1bd0517e48963199"
+"cargo-binstall-x86_64-unknown-linux-musl.tgz" = "sha256:d073d4e8901e176b0f625845f9a0bbd926a063017991d7cc0c863e6b884d2d59"
 
 [tools."cargo:cargo-edit"]
 version = "0.13.0"
@@ -44,7 +46,7 @@ version = "0.2.3"
 backend = "cargo:toml-cli"
 
 [tools."cargo:usage-cli"]
-version = "1.7.3"
+version = "1.7.4"
 backend = "cargo:usage-cli"
 
 [tools.cosign]
diff --git a/src/task/mod.rs b/src/task/mod.rs
index 9ec9798cb2..d5bbc377f0 100644
--- a/src/task/mod.rs
+++ b/src/task/mod.rs
@@ -80,6 +80,8 @@ pub struct Task {
     pub silent: bool,
     #[serde(default)]
     pub tools: IndexMap<String, String>,
+    #[serde(default)]
+    pub usage: String,
 
     // normal type
     #[serde(default, deserialize_with = "deserialize_arr")]
@@ -562,6 +564,7 @@ impl Default for Task {
             file: None,
             quiet: false,
             tools: Default::default(),
+            usage: "".to_string(),
         }
     }
 }
diff --git a/src/task/task_script_parser.rs b/src/task/task_script_parser.rs
index 426f809775..ca78c0b68d 100644
--- a/src/task/task_script_parser.rs
+++ b/src/task/task_script_parser.rs
@@ -295,10 +295,11 @@ impl TaskScriptParser {
             })
             .collect();
         cmd.flags = input_flags.lock().unwrap().clone();
-        let spec = usage::Spec {
+        let mut spec = usage::Spec {
             cmd,
             ..Default::default()
         };
+        spec.merge(task.usage.parse()?);
 
         Ok((scripts, spec))
     }