♻️ refactor(run): align CLI flags with jq and move actions to subcommnds

README.md

@@ -384,7 +384,7 @@ mq conv document.docx | mq -A 'section::section("Summary")'
 mq conv slides.pdf | mq view
 ```
 
-Run `mq --list` to see all available subcommands (built-in and external).
+Run `mq commands` to see all available subcommands (built-in and external).
 
 ## External Subcommands
 

crates/mq-lang/src/mqc.rs

@@ -116,7 +116,7 @@ pub enum MqcError {
     #[diagnostic(
         code(mq::mqc::module_let_runtime_value),
         help(
-            "Module-level `let` values are computed once, when the .mqc file is compiled, so they cannot read --args/--argjson values. A module can't see them, so read \"{name}\" outside the module instead."
+            "Module-level `let` values are computed once, when the .mqc file is compiled, so they cannot read --arg/--argjson values. A module can't see them, so read \"{name}\" outside the module instead."
         )
     )]
     ModuleLevelNotDefined {
@@ -177,7 +177,7 @@ impl Mqc {
         &self.dependencies
     }
 
-    /// Engine globals the program reads at run time (e.g. `--args` values).
+    /// Engine globals the program reads at run time (e.g. `--arg` values).
     pub fn external_globals(&self) -> &[String] {
         &self.meta.external_globals
     }

crates/mq-lang/src/mqc/tests.rs

@@ -777,7 +777,7 @@ fn constant_expr() -> impl Strategy<Value = String> {
     ]
 }
 
-/// Names that only exist at run time, such as `--args` values.
+/// Names that only exist at run time, such as `--arg` values.
 fn runtime_name() -> impl Strategy<Value = String> {
     "rt_[a-z]{1,8}"
 }

crates/mq-run/src/cli/mqc.rs

@@ -163,7 +163,7 @@ impl Cli {
     /// builtin would not shadow it as it does when running the query from source.
     fn reject_builtin_named_globals(&self) -> miette::Result<()> {
         let options = [
-            ("--args", &self.input.args),
+            ("--arg", &self.input.arg),
             ("--argjson", &self.input.argjson),
             ("--rawfile", &self.input.raw_file),
             ("--slurpfile", &self.input.slurp_file),

crates/mq-run/tests/batch_modes_tests.rs

@@ -100,7 +100,7 @@ fn test_count_matches_single_file_counts(#[case] query: &str, #[case] with_csv:
     };
     let counts: Vec<usize> = files
         .iter()
-        .map(|file| stdout(dir.path(), &["-c", query], &[file]).trim().parse().unwrap())
+        .map(|file| stdout(dir.path(), &["--count", query], &[file]).trim().parse().unwrap())
         .collect();
     let mut expected: String = files
         .iter()
@@ -109,7 +109,7 @@ fn test_count_matches_single_file_counts(#[case] query: &str, #[case] with_csv:
         .collect();
     expected.push_str(&format!("total: {}\n", counts.iter().sum::<usize>()));
 
-    assert_eq!(stdout(dir.path(), &["-c", query], &files), expected);
+    assert_eq!(stdout(dir.path(), &["--count", query], &files), expected);
 }
 
 #[rstest]
@@ -148,15 +148,15 @@ fn test_mqc_count_matches_single_file_counts() {
         .args(["compile", ".h", "-o", "query.mqc"])
         .assert()
         .success();
-    let output = stdout(dir.path(), &["-c", "query.mqc"], MARKDOWN);
+    let output = stdout(dir.path(), &["--count", "query.mqc"], MARKDOWN);
     let mut expected: String = MARKDOWN.iter().map(|file| format!("{file}: 2\n")).collect();
     expected.push_str(&format!("total: {}\n", MARKDOWN.len() * 2));
     assert_eq!(output, expected);
 }
 
 #[rstest]
 fn test_invalid_query_fails_in_every_mode(
-    #[values(&["-P", "1000"], &["-P", "0"], &["-c"], &["-S", r#""---""#])] mode: &[&str],
+    #[values(&["-P", "1000"], &["-P", "0"], &["--count"], &["-S", r#""---""#])] mode: &[&str],
 ) {
     let dir = fixture();
     let assert = mq(dir.path())

crates/mq-run/tests/integration_tests.rs

@@ -200,7 +200,7 @@ fn test_compact_rejected_without_json_format() {
 "#)
 )]
 #[case::args(
-    vec!["--unbuffered", "--args", "val1", "test", "select(contains(val1))"],
+    vec!["--unbuffered", "--arg", "val1", "test", "select(contains(val1))"],
     "# **title**\n\n- test1\n- test2",
     Some("- test1\n- test2\n")
 )]
@@ -1597,10 +1597,10 @@ fn test_count_stdin(
 }
 
 #[test]
-fn test_count_short_flag() -> Result<(), Box<dyn std::error::Error>> {
+fn test_count_flag() -> Result<(), Box<dyn std::error::Error>> {
     let mut cmd = cargo::cargo_bin_cmd!("mq");
     cmd.arg("--unbuffered")
-        .arg("-c")
+        .arg("--count")
         .arg(".h2")
         .write_stdin("# h1\n\n## h2\n\n## h2b\n")
         .assert()

crates/mq-run/tests/mqc_tests.rs

@@ -142,17 +142,17 @@ fn test_run_reads_args_at_run_time() {
     compile(dir.path(), r#"s"hello ${name}""#, &[]);
     let output = stdout(
         mq(dir.path())
-            .args(["query.mqc", "-I", "null", "--args", "name", "mq"])
+            .args(["query.mqc", "-I", "null", "--arg", "name", "mq"])
             .assert(),
     );
     assert_eq!(output.trim(), "hello mq");
 }
 
 #[rstest]
-#[case::args(&["--args", "len", "5"], "--args len")]
+#[case::args(&["--arg", "len", "5"], "--arg len")]
 #[case::argjson(&["--argjson", "upcase", "1"], "--argjson upcase")]
-#[case::coroutine_builtin(&["--args", "next", "x"], "--args next")]
-#[case::later_pair(&["--args", "name", "mq", "--args", "len", "5"], "--args len")]
+#[case::coroutine_builtin(&["--arg", "next", "x"], "--arg next")]
+#[case::later_pair(&["--arg", "name", "mq", "--arg", "len", "5"], "--arg len")]
 fn test_run_rejects_globals_named_after_builtins(#[case] flags: &[&str], #[case] expected: &str) {
     let dir = TempDir::new().unwrap();
     compile(dir.path(), "len", &[]);
@@ -510,7 +510,7 @@ fn test_run_reads_runtime_names_outside_module(#[case] query: &str) {
     for value in ["hello", "world"] {
         let output = stdout(
             mq(dir.path())
-                .args(["query.mqc", "-I", "null", "--args", "arg", value])
+                .args(["query.mqc", "-I", "null", "--arg", "arg", value])
                 .assert(),
         );
         assert_eq!(output.trim(), value);

docs/books/src/reference/modules_and_imports.md

@@ -42,7 +42,7 @@ A module, inline or imported, sees only:
 - Built-in functions.
 - Modules it imports itself, and inline modules defined earlier (by qualified name).
 
-It does not see the query's own `let`, `var`, or `def` bindings, modules imported outside it, or runtime values such as `__FILE__` and `--args`. Referring to them is an error.
+It does not see the query's own `let`, `var`, or `def` bindings, modules imported outside it, or runtime values such as `__FILE__` and `--arg`. Referring to them is an error.
 
 ```mq
 module csv_tools:

docs/books/src/start/compiled-programs.md

@@ -37,7 +37,7 @@ Module-level `let` values are computed once, when the program is compiled.
 
 ## What is read at run time
 
-- Values from `--args`, `--argjson`, `--rawfile`, `--slurpfile`, and `__FILE__`, outside modules. A module can't read them. A name that matches a builtin function, such as `--args len 5`, is rejected: the program resolved that name to the builtin when it was compiled.
+- Values from `--arg`, `--argjson`, `--rawfile`, `--slurpfile`, and `__FILE__`, outside modules. A module can't read them. A name that matches a builtin function, such as `--args len 5`, is rejected: the program resolved that name to the builtin when it was compiled.
 - Permissions such as `--allow-read` and `--allow-net`. A compiled program gets no permission that the running `mq` does not grant. Permissions passed to `mq compile` apply only while module-level `let` values are computed, and are not saved.
 - Environment variables read with interpolation, such as `s"${$HOME}"` (with `--allow-env`). `mq compile` rejects a bare `$VAR`, and any environment read in a module-level `let`, because the value would be saved in the file.
 

docs/books/src/start/external_subcommands.md

@@ -13,10 +13,10 @@ The first match found is used.
 
 ## Listing Available Subcommands
 
-Use the `--list` flag to see all available subcommands:
+Use the `commands` subcommand to see all available subcommands (add `--json` for machine-readable output):
 
 ```sh
-mq --list
+mq commands
 ```
 
 This makes it easy to add your own tools and workflows to `mq` without modifying the core binary.

scripts/bump_version.sh

@@ -37,14 +37,14 @@ echo "Bumping version: ${CURRENT_VERSION} -> ${MQ_VERSION}"
 
 # Update the workspace Cargo.toml
 tmpfile=$(mktemp)
-"$MQ" -I raw --args version $MQ_VERSION 'import "bump_version" | bump_version::crates_version(self, version)' ../Cargo.toml > "$tmpfile" && mv "$tmpfile" ../Cargo.toml
+"$MQ" -I raw --arg version $MQ_VERSION 'import "bump_version" | bump_version::crates_version(self, version)' ../Cargo.toml > "$tmpfile" && mv "$tmpfile" ../Cargo.toml
 
 # Update package.json files
 for dir in ../packages ../editors; do
     for package in "$dir"/*; do
         if [ -f "$package/package.json" ]; then
             tmpfile=$(mktemp)
-            "$MQ" -I raw --args version $MQ_VERSION 'import "bump_version" | bump_version::npm_version(self, version)' "$package/package.json" > "$tmpfile" && mv "$tmpfile" "$package/package.json"
+            "$MQ" -I raw --arg version $MQ_VERSION 'import "bump_version" | bump_version::npm_version(self, version)' "$package/package.json" > "$tmpfile" && mv "$tmpfile" "$package/package.json"
         fi
     done
 done
@@ -53,15 +53,15 @@ done
 JETBRAINS_GRADLE_PROPERTIES="../editors/jetbrains/gradle.properties"
 if [ -f "$JETBRAINS_GRADLE_PROPERTIES" ]; then
     tmpfile=$(mktemp)
-    "$MQ" -I text --args version $MQ_VERSION 'import "bump_version" | bump_version::gradle_version(version)' "$JETBRAINS_GRADLE_PROPERTIES" > "$tmpfile" && mv "$tmpfile" "$JETBRAINS_GRADLE_PROPERTIES"
+    "$MQ" -I text --arg version $MQ_VERSION 'import "bump_version" | bump_version::gradle_version(version)' "$JETBRAINS_GRADLE_PROPERTIES" > "$tmpfile" && mv "$tmpfile" "$JETBRAINS_GRADLE_PROPERTIES"
 fi
 
 # Update README.md with the new version
-"$MQ" -U --args VERSION $MQ_VERSION 'import "bump_version" | bump_version::code_block_version(VERSION)' $README > README.md.tmp \
+"$MQ" -U --arg VERSION $MQ_VERSION 'import "bump_version" | bump_version::code_block_version(VERSION)' $README > README.md.tmp \
   && mv README.md.tmp $README
 
 # Update INSTALL_DOC.md with the new version
-"$MQ" -U --args VERSION $MQ_VERSION 'import "bump_version" | bump_version::code_block_version(VERSION)' $INSTALL_DOC > INSTALL_DOC.md.tmp \
+"$MQ" -U --arg VERSION $MQ_VERSION 'import "bump_version" | bump_version::code_block_version(VERSION)' $INSTALL_DOC > INSTALL_DOC.md.tmp \
   && mv INSTALL_DOC.md.tmp $INSTALL_DOC
 
 echo "Done. Review with 'git diff', then:"