diff --git a/PLAN.md b/PLAN.md index 872b49c36..86e4d6fb9 100644 --- a/PLAN.md +++ b/PLAN.md @@ -322,14 +322,12 @@ tasks --usage"`, so task names are meant to come from running that. usage-argv d tables. Same dispatch shape usage-cli uses today, without requiring `usage` on the end user's machine. bash, zsh, fish and PowerShell, behind the `complete` feature and asked for with `#[usage(completion)]`. -- [ ] **Docs and manpages** — no new code: confirm the emitted KDL feeds - `usage g markdown|manpage` exactly as a clap-derived spec does today, so an - adopter's docs pipeline does not change. **usage-cli already does this for - itself** (`mise run render:usage-cli-completions` regenerates - `docs/cli/reference` and `cli/assets/usage.1` from the derive's spec). What - has not been confirmed is a fleet spec: the same generators over a - shadow-emitted KDL versus the checked-in `.usage.kdl`. That confirmation - lives under **Trying the fleet**. +- [x] **Docs and manpages** — the emitted KDL feeds `usage g markdown|manpage` + the same way a clap-derived spec does. usage-cli already regenerates + `docs/cli/reference` and `cli/assets/usage.1` from the derive's spec + (`mise run render:usage-cli-completions`). The gate now asks the same of + a clap CLI: `benches/gate/tests/fleet.rs` holds communique's markdown + and manpage to the checked-in spec. - [x] **Diagnostics** — rich errors behind the `diagnostics` feature. The hot path returns a compact code; rendering re-examines the command line only once it has already failed, and says what clap would have said, colour included, down to @@ -595,11 +593,11 @@ looking at the clap surface, not only at the spec. shadows cannot see delimiter-split flags that mise, hk, pitchfork and aube all declare. tak currently has no `usage` subcommand at all, so it cannot even produce a fresh spec without one. -- [ ] **Docs and manpages on a fleet spec.** Render markdown and a manpage from - a shadow-emitted KDL and from the checked-in spec; they should match. - usage-cli's own `render:usage-cli-completions` already does this for - `usage`. One of the smaller CLIs — communique is five commands — is enough - to catch a generator that only agrees on usage-cli's shape. +- [x] **Docs and manpages on a fleet spec.** communique's checked-in spec and + the KDL its shadow emits render the same markdown (index and every + command) and the same manpage. usage-cli's own + `render:usage-cli-completions` already does this for `usage`; the gate + now asks it of a clap CLI. - [ ] **A typed rewrite of one small CLI, not a String shadow.** `gen-shadow` types every field as `String`. The derive already holds `PathBuf`, `OsString`, `ValueEnum`, `FromStr`, `flatten`, `Option`/`Vec`. usage-cli diff --git a/benches/gate/tests/fleet.rs b/benches/gate/tests/fleet.rs index 18a9f571e..f202f0163 100644 --- a/benches/gate/tests/fleet.rs +++ b/benches/gate/tests/fleet.rs @@ -171,3 +171,63 @@ fleet! { "tak" => shadow_tak from "../../fleet/tak.usage.kdl", "communique" => shadow_communique from "../../fleet/communique.usage.kdl", } + +/// Markdown and a manpage from the checked-in spec versus from the shadow's +/// emitted KDL. usage-cli already does this for `usage`; communique is five +/// commands, which is enough to catch a generator that only agrees on that +/// shape. +#[test] +fn communique_docs_match_the_checked_in_spec() { + let fixture: LibSpec = include_str!("../../fleet/communique.usage.kdl") + .parse() + .expect("communique's fixture should parse"); + let emitted: LibSpec = shadow_communique::Cli::to_kdl() + .parse() + .expect("the shadow's emitted spec should parse"); + + let fixture_md = markdown(&fixture); + let emitted_md = markdown(&emitted); + assert_eq!( + fixture_md, + emitted_md, + "markdown from the shadow's KDL should match the checked-in spec\n{}", + first_diff(&emitted_md, &fixture_md) + ); + + let fixture_man = manpage(&fixture); + let emitted_man = manpage(&emitted); + assert_eq!( + fixture_man, + emitted_man, + "the manpage from the shadow's KDL should match the checked-in spec\n{}", + first_diff(&emitted_man, &fixture_man) + ); +} + +fn markdown(spec: &LibSpec) -> String { + let renderer = usage::docs::markdown::MarkdownRenderer::new(spec.clone()).with_multi(true); + let mut pages = vec![renderer.render_index().expect("the index should render")]; + let mut cmds = Vec::new(); + walk_lib_cmds(&spec.cmd, &mut cmds); + for cmd in cmds { + pages.push( + renderer + .render_cmd(cmd) + .unwrap_or_else(|e| panic!("{} should render: {e}", cmd.name)), + ); + } + pages.join("\n---\n") +} + +fn manpage(spec: &LibSpec) -> String { + usage::docs::manpage::ManpageRenderer::new(spec.clone()) + .render() + .expect("the manpage should render") +} + +fn walk_lib_cmds<'a>(cmd: &'a SpecCommand, out: &mut Vec<&'a SpecCommand>) { + out.push(cmd); + for sub in cmd.subcommands.values() { + walk_lib_cmds(sub, out); + } +} diff --git a/benches/shadows/aube/src/lib.rs b/benches/shadows/aube/src/lib.rs index ad57e2377..1c5245059 100644 --- a/benches/shadows/aube/src/lib.rs +++ b/benches/shadows/aube/src/lib.rs @@ -9,6 +9,7 @@ use usage_derive::{Args, Cli, Subcommands}; /// Bootstrap aube's cached node-gyp and print the executable path #[derive(Args)] +#[usage(effect = "write")] pub struct NodeGypBootstrapArgs { #[usage(arg, name = "PROJECT_DIR")] pub project_dir: ::std::string::String, @@ -16,6 +17,7 @@ pub struct NodeGypBootstrapArgs { /// Get a package's public or restricted status #[derive(Args)] +#[usage(effect = "read")] pub struct AccessGetStatusArgs { /// Package name #[usage(arg, name = "PACKAGE")] @@ -24,6 +26,7 @@ pub struct AccessGetStatusArgs { /// Get package visibility status #[derive(Args)] +#[usage(effect = "read")] pub struct AccessGetArgs { #[usage(subcommand)] pub command: AccessGetCommands, @@ -38,6 +41,7 @@ pub enum AccessGetCommands { /// Grant a team read-only or read-write access to a package #[derive(Args)] +#[usage(effect = "write")] pub struct AccessGrantArgs { /// `read-only` or `read-write` #[usage(arg, name = "PERMISSIONS")] @@ -52,6 +56,7 @@ pub struct AccessGrantArgs { /// List collaborators for a package, optionally filtering to one user #[derive(Args)] +#[usage(effect = "read")] pub struct AccessListCollaboratorsArgs { /// Package name #[usage(arg, name = "PACKAGE")] @@ -63,6 +68,7 @@ pub struct AccessListCollaboratorsArgs { /// List packages visible to the current user or an optional entity #[derive(Args)] +#[usage(effect = "read")] pub struct AccessListPackagesArgs { /// User, `@organization`, or `@scope:team` #[usage(arg, name = "ENTITY")] @@ -71,6 +77,7 @@ pub struct AccessListPackagesArgs { /// List packages visible to a user, organization, or team #[derive(Args)] +#[usage(effect = "read")] pub struct AccessListArgs { #[usage(subcommand)] pub command: AccessListCommands, @@ -88,6 +95,7 @@ pub enum AccessListCommands { /// Alias for `list packages` #[derive(Args)] +#[usage(effect = "read")] pub struct AccessLsArgs { /// User, `@organization`, or `@scope:team`. Also accepts pnpm's `packages [ENTITY]` compatibility form. Accepted forms are `aube access ls [ENTITY]` and `aube access ls packages [ENTITY]` #[usage(arg, name = "ENTITIES")] @@ -96,6 +104,7 @@ pub struct AccessLsArgs { /// Revoke a team's access to a package #[derive(Args)] +#[usage(effect = "destructive")] pub struct AccessRevokeArgs { /// Team in `@scope:team` form #[usage(arg, name = "TEAM")] @@ -107,6 +116,7 @@ pub struct AccessRevokeArgs { /// Set package visibility or a publish MFA requirement #[derive(Args)] +#[usage(effect = "write")] pub struct AccessSetArgs { /// `status=public|private|restricted` or `mfa=none|publish|automation` #[usage(arg, name = "SETTING")] @@ -118,6 +128,7 @@ pub struct AccessSetArgs { /// Manage package access and visibility on the registry #[derive(Args)] +#[usage(effect = "read")] pub struct AccessArgs { /// Emit registry responses as JSON when the subcommand has a result #[usage(long = "json")] @@ -195,6 +206,7 @@ pub enum AccessCommands { /// Emit shell activation code for runtime tool shims #[derive(Args)] +#[usage(effect = "write")] pub struct ActivateArgs { /// Shell to emit activation code for #[usage(arg, name = "SHELL", choices("bash", "fish", "zsh"))] @@ -203,6 +215,7 @@ pub struct ActivateArgs { /// Add a dependency #[derive(Args)] +#[usage(effect = "write")] pub struct AddArgs { /// Add as dev dependency #[usage(long = "save-dev", short = 'D')] @@ -373,6 +386,7 @@ pub struct AddArgs { } #[derive(Args)] +#[usage(effect = "write")] pub struct ApproveBuildsArgs { /// Approve every pending ignored build without prompting #[usage(long = "all")] @@ -392,7 +406,8 @@ pub struct ApproveBuildsArgs { /// Check installed packages against the registry advisory DB #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube audit\n Severity Package Vulnerable Title\n moderate minimatch <3.0.5 Regular Expression Denial of Service\n https://github.com/advisories/GHSA-f8q6-p94x\n\n 1 vulnerability found\n\n # Only fail on high and above\n $ aube audit --audit-level high\n\n # Skip optional deps and dev deps\n $ aube audit --prod --no-optional\n\n # Pipe into jq\n $ aube audit --json | jq '.advisories | length'\n\n # Clean\n $ aube audit\n No known vulnerabilities found" + after_long_help = "Examples:\n\n $ aube audit\n Severity Package Vulnerable Title\n moderate minimatch <3.0.5 Regular Expression Denial of Service\n https://github.com/advisories/GHSA-f8q6-p94x\n\n 1 vulnerability found\n\n # Only fail on high and above\n $ aube audit --audit-level high\n\n # Skip optional deps and dev deps\n $ aube audit --prod --no-optional\n\n # Pipe into jq\n $ aube audit --json | jq '.advisories | length'\n\n # Clean\n $ aube audit\n No known vulnerabilities found", + effect = "read" )] pub struct AuditArgs { #[usage( @@ -493,7 +508,8 @@ pub struct AuditArgs { /// Print the path to `node_modules/.bin` #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube bin\n /home/user/project/node_modules/.bin\n\n $ aube bin -g\n /home/user/.local/share/aube/global/node_modules/.bin\n\n # From a workspace package, -w prints the workspace-root bin directory\n $ cd packages/app\n $ aube bin\n /home/user/project/packages/app/node_modules/.bin\n $ aube bin -w\n /home/user/project/node_modules/.bin\n\n # Extend PATH with the project bin directory\n $ export PATH=\"$(aube bin):$PATH\"" + after_long_help = "Examples:\n\n $ aube bin\n /home/user/project/node_modules/.bin\n\n $ aube bin -g\n /home/user/.local/share/aube/global/node_modules/.bin\n\n # From a workspace package, -w prints the workspace-root bin directory\n $ cd packages/app\n $ aube bin\n /home/user/project/packages/app/node_modules/.bin\n $ aube bin -w\n /home/user/project/node_modules/.bin\n\n # Extend PATH with the project bin directory\n $ export PATH=\"$(aube bin):$PATH\"", + effect = "read" )] pub struct BinArgs { /// Print the global bin directory instead of the project's @@ -512,7 +528,8 @@ pub struct BinArgs { /// Open package bug tracker URLs #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube bugs\n\n $ aube bugs react\n\n $ aube issues react react-dom" + after_long_help = "Examples:\n\n $ aube bugs\n\n $ aube bugs react\n\n $ aube issues react react-dom", + effect = "read" )] pub struct BugsArgs { #[usage( @@ -563,6 +580,7 @@ pub struct BugsArgs { } #[derive(Args)] +#[usage(effect = "write")] pub struct CacheDeleteArgs { #[usage( arg, @@ -575,6 +593,7 @@ pub struct CacheDeleteArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct CacheListArgs { #[usage( arg, @@ -586,10 +605,12 @@ pub struct CacheListArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct CacheListRegistriesArgs {} /// Remove stale extracted primer files from the metadata cache #[derive(Args)] +#[usage(effect = "write")] pub struct CachePruneArgs { /// Minimum age in days before an old primer file is removed #[usage(long = "age-days", value_name = "AGE_DAYS", default = "30")] @@ -600,6 +621,7 @@ pub struct CachePruneArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct CacheViewArgs { /// Dump the raw on-disk cache JSON instead of a summary #[usage(long = "json")] @@ -611,6 +633,7 @@ pub struct CacheViewArgs { /// Inspect and manage the packument metadata cache #[derive(Args)] +#[usage(effect = "read")] pub struct CacheArgs { #[usage(subcommand)] pub command: CacheCommands, @@ -653,6 +676,7 @@ pub enum CacheCommands { /// Print a file from the global store by integrity or hex hash #[derive(Args)] +#[usage(effect = "read")] pub struct CatFileArgs { #[usage( arg, @@ -665,6 +689,7 @@ pub struct CatFileArgs { /// Print the cached package index JSON for `@` #[derive(Args)] +#[usage(effect = "read")] pub struct CatIndexArgs { #[usage( arg, @@ -677,7 +702,8 @@ pub struct CatIndexArgs { #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube check\n node_modules symlink tree is consistent (checked 248 packages).\n\n # With issues\n $ aube check\n 2 broken dependency links found:\n\n vscode-languageserver@9.0.1\n ✕ cannot resolve: vscode-languageserver-protocol@3.17.5\n\n vscode-languageserver-protocol@3.17.5\n ✕ cannot resolve: vscode-languageserver-types@3.17.5\n ✕ cannot resolve: vscode-jsonrpc@8.2.1\n\n # Machine-readable\n $ aube check --json" + after_long_help = "Examples:\n\n $ aube check\n node_modules symlink tree is consistent (checked 248 packages).\n\n # With issues\n $ aube check\n 2 broken dependency links found:\n\n vscode-languageserver@9.0.1\n ✕ cannot resolve: vscode-languageserver-protocol@3.17.5\n\n vscode-languageserver-protocol@3.17.5\n ✕ cannot resolve: vscode-languageserver-types@3.17.5\n ✕ cannot resolve: vscode-jsonrpc@8.2.1\n\n # Machine-readable\n $ aube check --json", + effect = "read" )] pub struct CheckArgs { /// Emit a JSON report instead of the human-readable list @@ -686,6 +712,7 @@ pub struct CheckArgs { } #[derive(Args)] +#[usage(effect = "write")] pub struct CiArgs { /// Skip lifecycle scripts (no-op; aube already skips by default) #[usage(long = "ignore-scripts")] @@ -761,6 +788,7 @@ pub struct CiArgs { } #[derive(Args)] +#[usage(effect = "write")] pub struct CleanArgs { #[usage( help = "Also remove lockfiles at the workspace root", @@ -773,6 +801,7 @@ pub struct CleanArgs { /// Generate shell completions (bash, zsh, fish) #[derive(Args)] +#[usage(effect = "read")] pub struct CompletionArgs { /// Emit dynamic candidates for the shell completion engine #[usage( @@ -792,6 +821,7 @@ pub struct CompletionArgs { /// Delete a key from aube config or the selected `.npmrc` file #[derive(Args)] +#[usage(effect = "destructive")] pub struct ConfigDeleteArgs { /// Shortcut for `--location project` #[usage(long = "local")] @@ -816,6 +846,7 @@ pub struct ConfigDeleteArgs { /// Explain a known setting, including defaults and supported config sources #[derive(Args)] +#[usage(effect = "read")] pub struct ConfigExplainArgs { /// Setting key, `.npmrc` alias, env var, workspace YAML key, or CLI flag #[usage(arg, name = "KEY")] @@ -824,6 +855,7 @@ pub struct ConfigExplainArgs { /// Search known settings by name, source key, or description #[derive(Args)] +#[usage(effect = "read")] pub struct ConfigFindArgs { /// Words to search for #[usage(arg, name = "QUERY", required)] @@ -832,6 +864,7 @@ pub struct ConfigFindArgs { /// Print the effective value of a key #[derive(Args)] +#[usage(effect = "read")] pub struct ConfigGetArgs { #[usage( help = "Emit the value as JSON", @@ -862,6 +895,7 @@ pub struct ConfigGetArgs { /// Print every key/value from aube config and selected `.npmrc` file(s) #[derive(Args)] +#[usage(effect = "read")] pub struct ConfigListArgs { #[usage( help = "Also list settings that have no value set", @@ -893,6 +927,7 @@ pub struct ConfigListArgs { /// Write a key=value pair to aube config or the selected `.npmrc` file #[derive(Args)] +#[usage(effect = "write")] pub struct ConfigSetArgs { /// Shortcut for `--location project` #[usage(long = "local")] @@ -916,10 +951,12 @@ pub struct ConfigSetArgs { /// Browse known settings in an interactive terminal UI #[derive(Args)] +#[usage(effect = "write")] pub struct ConfigTuiArgs {} /// Read and write settings in `.npmrc` #[derive(Args)] +#[usage(effect = "read")] pub struct ConfigArgs { #[usage( help = "Also list settings that have no value set", @@ -1033,6 +1070,7 @@ pub struct CreateArgs { /// Re-resolve the lockfile to collapse duplicate versions #[derive(Args)] +#[usage(effect = "write")] pub struct DedupeArgs { #[usage( help = "Check whether dedupe would change the lockfile; don't write anything", @@ -1109,6 +1147,7 @@ pub struct DedupeArgs { /// Deploy a workspace package into a target directory with deps inlined #[derive(Args)] +#[usage(effect = "write")] pub struct DeployArgs { #[usage( help = "Install only `devDependencies`", @@ -1219,6 +1258,7 @@ pub struct DeployArgs { /// Mark published versions of a package as deprecated on the registry #[derive(Args)] +#[usage(effect = "write")] pub struct DeprecateArgs { /// Don't PUT anything — print which versions would be touched and exit #[usage(long = "dry-run")] @@ -1286,6 +1326,7 @@ pub struct DeprecateArgs { /// Report deprecated packages in the resolved dependency graph #[derive(Args)] +#[usage(effect = "read")] pub struct DeprecationsArgs { /// Exit with a non-zero status if any deprecations are found #[usage(long = "exit-code")] @@ -1342,6 +1383,7 @@ pub struct DeprecationsArgs { /// Show critical path / starvation / per-pkg lifecycle from a saved trace #[derive(Args)] +#[usage(effect = "read")] pub struct DiagAnalyzeArgs { /// Trace JSONL #[usage(arg, name = "PATH")] @@ -1350,6 +1392,7 @@ pub struct DiagAnalyzeArgs { /// Diff two diag JSONL traces and surface per-operation regressions #[derive(Args)] +#[usage(effect = "read")] pub struct DiagCompareArgs { /// Minimum |Δsum_ms| to surface (default 50) #[usage(long = "min-delta-ms", value_name = "MIN_DELTA_MS", default = "50")] @@ -1367,6 +1410,7 @@ pub struct DiagCompareArgs { /// Diagnostic trace analysis (compare/analyze JSONL traces) #[derive(Args)] +#[usage(effect = "read")] pub struct DiagArgs { #[usage(subcommand)] pub command: DiagCommands, @@ -1383,6 +1427,7 @@ pub enum DiagCommands { } #[derive(Args)] +#[usage(effect = "write")] pub struct DistTagAddArgs { /// One-time password from a 2FA authenticator; sent as `npm-otp` #[usage(long = "otp", value_name = "OTP")] @@ -1396,6 +1441,7 @@ pub struct DistTagAddArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct DistTagLsArgs { #[usage( arg, @@ -1408,6 +1454,7 @@ pub struct DistTagLsArgs { /// Remove a dist-tag from a package #[derive(Args)] +#[usage(effect = "destructive")] pub struct DistTagRmArgs { /// One-time password from a 2FA authenticator; sent as `npm-otp` #[usage(long = "otp", value_name = "OTP")] @@ -1422,6 +1469,7 @@ pub struct DistTagRmArgs { /// Manage package distribution tags on the registry #[derive(Args)] +#[usage(effect = "read")] pub struct DistTagArgs { #[usage( help = "Number of retry attempts for failed registry fetches", @@ -1595,7 +1643,8 @@ pub struct DlxArgs { /// Run broad install-health diagnostics #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube doctor\n version: 1.0.0-beta.4\n node: v22.11.0\n ...\n No problems found\n\n $ aube doctor --json | jq .warnings" + after_long_help = "Examples:\n\n $ aube doctor\n version: 1.0.0-beta.4\n node: v22.11.0\n ...\n No problems found\n\n $ aube doctor --json | jq .warnings", + effect = "read" )] pub struct DoctorArgs { /// Emit a machine-readable JSON report instead of the grouped text @@ -1737,6 +1786,7 @@ pub struct ExecArgs { /// Download lockfile dependencies into the store without linking node_modules #[derive(Args)] +#[usage(effect = "write")] pub struct FetchArgs { /// Only fetch devDependencies #[usage(long = "dev", short = 'D')] @@ -1814,7 +1864,8 @@ pub struct FetchArgs { /// List packages whose cached index references a given file hash #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # Accepts integrity strings\n $ aube find-hash sha512-abc123...\n lodash@4.17.21\tpackage/lodash.js\n express@4.19.2\tnode_modules/lodash/lodash.js\n\n # ...or raw hex digests\n $ aube find-hash 5d41402abc4b2a76b9719d911017c592...\n\n # Machine-readable\n $ aube find-hash --json sha512-abc123..." + after_long_help = "Examples:\n\n # Accepts integrity strings\n $ aube find-hash sha512-abc123...\n lodash@4.17.21\tpackage/lodash.js\n express@4.19.2\tnode_modules/lodash/lodash.js\n\n # ...or raw hex digests\n $ aube find-hash 5d41402abc4b2a76b9719d911017c592...\n\n # Machine-readable\n $ aube find-hash --json sha512-abc123...", + effect = "read" )] pub struct FindHashArgs { #[usage( @@ -1876,6 +1927,7 @@ pub struct FindHashArgs { /// Alias for `config get` (hidden; prefer `config get`) #[derive(Args)] +#[usage(effect = "read")] pub struct GetArgs { #[usage( help = "Emit the value as JSON", @@ -1907,7 +1959,8 @@ pub struct GetArgs { /// Print packages whose install scripts were skipped by `pnpm.allowBuilds` #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube ignored-builds\n The following builds were ignored during install:\n esbuild@0.20.2\n puppeteer@22.8.0\n\n # When nothing was skipped\n $ aube ignored-builds\n No ignored builds.\n\n # Approve them for this project\n $ aube approve-builds" + after_long_help = "Examples:\n\n $ aube ignored-builds\n The following builds were ignored during install:\n esbuild@0.20.2\n puppeteer@22.8.0\n\n # When nothing was skipped\n $ aube ignored-builds\n No ignored builds.\n\n # Approve them for this project\n $ aube approve-builds", + effect = "read" )] pub struct IgnoredBuildsArgs { /// Operate on globally-installed packages instead of the current project @@ -1917,6 +1970,7 @@ pub struct IgnoredBuildsArgs { /// Convert a supported lockfile into aube-lock.yaml #[derive(Args)] +#[usage(effect = "write")] pub struct ImportArgs { /// Overwrite an existing aube-lock.yaml #[usage(long = "force")] @@ -1938,6 +1992,7 @@ pub struct ImportArgs { /// Create a `package.json` in the current directory #[derive(Args)] +#[usage(effect = "write")] pub struct InitArgs { /// Create a `package.json` with only the bare minimum of required fields #[usage(long = "bare")] @@ -2001,6 +2056,7 @@ pub struct InitArgs { /// Install all dependencies #[derive(Args)] +#[usage(effect = "write")] pub struct InstallArgs { /// Install only devDependencies #[usage(long = "dev", short = 'D')] @@ -2294,6 +2350,7 @@ pub struct InstallTestArgs { /// Alias for `list --long` (hidden; prefer `list --long`) #[derive(Args)] +#[usage(effect = "read")] pub struct LaArgs { /// Show only devDependencies #[usage(long = "dev", short = 'D')] @@ -2349,7 +2406,8 @@ pub struct LaArgs { /// Report the licenses of installed dependencies #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube licenses\n ├─ Apache-2.0\n │ └─ typescript@5.4.5\n ├─ ISC\n │ └─ semver@7.6.0\n └─ MIT\n ├─ express@4.19.2\n ├─ lodash@4.17.21\n └─ zod@3.23.8\n\n # Only production deps\n $ aube licenses --prod\n\n # Include each package's store path\n $ aube licenses --long\n\n # JSON array, one object per package\n $ aube licenses --json" + after_long_help = "Examples:\n\n $ aube licenses\n ├─ Apache-2.0\n │ └─ typescript@5.4.5\n ├─ ISC\n │ └─ semver@7.6.0\n └─ MIT\n ├─ express@4.19.2\n ├─ lodash@4.17.21\n └─ zod@3.23.8\n\n # Only production deps\n $ aube licenses --prod\n\n # Include each package's store path\n $ aube licenses --long\n\n # JSON array, one object per package\n $ aube licenses --json", + effect = "read" )] pub struct LicensesArgs { /// Show only devDependencies @@ -2419,6 +2477,7 @@ pub struct LicensesArgs { /// Link a local package globally, or into the current project #[derive(Args)] +#[usage(effect = "write")] pub struct LinkArgs { #[usage( help = "Register into (or resolve from) the global link registry", @@ -2435,7 +2494,8 @@ pub struct LinkArgs { /// Print the resolved dependency tree #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube list\n my-app@1.0.0 /home/user/project\n\n dependencies:\n ├── express 4.19.2\n ├── lodash 4.17.21\n └── zod 3.23.8\n\n devDependencies:\n ├── typescript 5.4.5\n └── vitest 1.6.0\n\n # Show the full transitive tree\n $ aube list --depth Infinity\n my-app@1.0.0 /home/user/project\n\n dependencies:\n ├─┬ express 4.19.2\n │ ├── accepts 1.3.8\n │ ├── body-parser 1.20.2\n │ └── ...\n\n # Only direct production deps\n $ aube list --prod\n\n # Machine-readable: one path per line (real store locations)\n $ aube list --parseable\n /home/user/project\n /home/user/project/node_modules/.aube/express@4.19.2/node_modules/express\n /home/user/project/node_modules/.aube/lodash@4.17.21/node_modules/lodash\n\n # Filter to a single package\n $ aube list express" + after_long_help = "Examples:\n\n $ aube list\n my-app@1.0.0 /home/user/project\n\n dependencies:\n ├── express 4.19.2\n ├── lodash 4.17.21\n └── zod 3.23.8\n\n devDependencies:\n ├── typescript 5.4.5\n └── vitest 1.6.0\n\n # Show the full transitive tree\n $ aube list --depth Infinity\n my-app@1.0.0 /home/user/project\n\n dependencies:\n ├─┬ express 4.19.2\n │ ├── accepts 1.3.8\n │ ├── body-parser 1.20.2\n │ └── ...\n\n # Only direct production deps\n $ aube list --prod\n\n # Machine-readable: one path per line (real store locations)\n $ aube list --parseable\n /home/user/project\n /home/user/project/node_modules/.aube/express@4.19.2/node_modules/express\n /home/user/project/node_modules/.aube/lodash@4.17.21/node_modules/lodash\n\n # Filter to a single package\n $ aube list express", + effect = "read" )] pub struct ListArgs { /// Show only devDependencies @@ -2491,6 +2551,7 @@ pub struct ListArgs { /// Alias for `list --long` (hidden; prefer `list --long`) #[derive(Args)] +#[usage(effect = "read")] pub struct LlArgs { /// Show only devDependencies #[usage(long = "dev", short = 'D')] @@ -2545,6 +2606,7 @@ pub struct LlArgs { /// Store a registry auth token in the user's ~/.npmrc #[derive(Args)] +#[usage(effect = "write")] pub struct LoginArgs { /// Authentication flow: `legacy` (token paste; default) or `web` (OAuth flow against `{registry}/-/v1/login`) #[usage(long = "auth-type", value_name = "TYPE", default = "legacy")] @@ -2602,6 +2664,7 @@ pub struct LoginArgs { /// Remove a registry auth token from the user's ~/.npmrc #[derive(Args)] +#[usage(effect = "destructive")] pub struct LogoutArgs { /// Scope whose registry mapping should also be removed (e.g. `@myorg`) #[usage(long = "scope", value_name = "SCOPE")] @@ -2661,7 +2724,8 @@ pub struct NodeArgs { /// Report dependencies whose installed version lags behind the registry #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube outdated\n Package Current Wanted Latest\n lodash 4.17.20 4.17.21 4.17.21\n typescript 5.3.3 5.3.3 5.4.5\n zod 3.22.4 3.22.4 3.23.8\n\n # Also print the package.json specifier and dep type\n $ aube outdated --long\n Package Current Wanted Latest\n lodash 4.17.20 4.17.21 4.17.21\n typescript 5.3.3 5.3.3 5.4.5\n\n lodash (dependencies): ^4.17.20\n typescript (devDependencies): ^5.3.0\n\n # Filter by prefix\n $ aube outdated '@babel/*'\n\n # Machine-readable (pnpm-compatible shape)\n $ aube outdated --json\n {\n \"lodash\": {\n \"current\": \"4.17.20\",\n \"wanted\": \"4.17.21\",\n \"latest\": \"4.17.21\"\n }\n }\n\n # Nothing to report exits 0\n $ aube outdated\n All dependencies up to date." + after_long_help = "Examples:\n\n $ aube outdated\n Package Current Wanted Latest\n lodash 4.17.20 4.17.21 4.17.21\n typescript 5.3.3 5.3.3 5.4.5\n zod 3.22.4 3.22.4 3.23.8\n\n # Also print the package.json specifier and dep type\n $ aube outdated --long\n Package Current Wanted Latest\n lodash 4.17.20 4.17.21 4.17.21\n typescript 5.3.3 5.3.3 5.4.5\n\n lodash (dependencies): ^4.17.20\n typescript (devDependencies): ^5.3.0\n\n # Filter by prefix\n $ aube outdated '@babel/*'\n\n # Machine-readable (pnpm-compatible shape)\n $ aube outdated --json\n {\n \"lodash\": {\n \"current\": \"4.17.20\",\n \"wanted\": \"4.17.21\",\n \"latest\": \"4.17.21\"\n }\n }\n\n # Nothing to report exits 0\n $ aube outdated\n All dependencies up to date.", + effect = "read" )] pub struct OutdatedArgs { /// Show only devDependencies @@ -2736,6 +2800,7 @@ pub struct OutdatedArgs { /// Manage package owners (not implemented — use `npm owner`) #[derive(Args)] +#[usage(effect = "read")] pub struct OwnerArgs { #[usage( help = "Number of retry attempts for failed registry fetches", @@ -2786,6 +2851,7 @@ pub struct OwnerArgs { /// Create a publishable `.tgz` tarball from the current project #[derive(Args)] +#[usage(effect = "write")] pub struct PackArgs { /// Don't write the tarball; print what would be packed #[usage(long = "dry-run")] @@ -2845,6 +2911,7 @@ pub struct PackArgs { /// Extract a package into an edit directory so it can be patched #[derive(Args)] +#[usage(effect = "write")] pub struct PatchArgs { #[usage( help = "Directory to extract the writable copy into", @@ -2870,6 +2937,7 @@ pub struct PatchArgs { /// Generate a `.patch` file from a `aube patch` edit directory #[derive(Args)] +#[usage(effect = "write")] pub struct PatchCommitArgs { #[usage( help = "Where to write the generated `.patch` file, relative to the project root", @@ -2890,6 +2958,7 @@ pub struct PatchCommitArgs { /// Remove patch entries from `pnpm.patchedDependencies` #[derive(Args)] +#[usage(effect = "destructive")] pub struct PatchRemoveArgs { #[usage( arg, @@ -2902,7 +2971,8 @@ pub struct PatchRemoveArgs { #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube peers check\n All peer dependencies are satisfied.\n\n # With issues\n $ aube peers check\n 1 unmet, 1 missing peer dependencies:\n\n ├─┬ @emotion/react@11.11.4\n │ └── ✕ unmet peer react@>=16.8: found 17.0.2\n └─┬ react-dom@18.2.0\n └── ✕ missing peer react@^18.0.0\n\n # Machine-readable\n $ aube peers check --json" + after_long_help = "Examples:\n\n $ aube peers check\n All peer dependencies are satisfied.\n\n # With issues\n $ aube peers check\n 1 unmet, 1 missing peer dependencies:\n\n ├─┬ @emotion/react@11.11.4\n │ └── ✕ unmet peer react@>=16.8: found 17.0.2\n └─┬ react-dom@18.2.0\n └── ✕ missing peer react@^18.0.0\n\n # Machine-readable\n $ aube peers check --json", + effect = "read" )] pub struct PeersCheckArgs { /// Emit a JSON report instead of the human-readable tree @@ -2912,6 +2982,7 @@ pub struct PeersCheckArgs { /// Inspect peer-dependency resolution from the lockfile #[derive(Args)] +#[usage(effect = "read")] pub struct PeersArgs { #[usage(subcommand)] pub command: PeersCommands, @@ -2930,6 +3001,7 @@ pub enum PeersCommands { /// Manage package.json entries (not implemented — use `npm pkg`) #[derive(Args)] +#[usage(effect = "read")] pub struct PkgArgs { #[usage( help = "Number of retry attempts for failed registry fetches", @@ -2981,7 +3053,8 @@ pub struct PkgArgs { /// Print the current package prefix directory #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube prefix\n /home/user/project\n\n $ aube prefix -g\n /home/user/.local/share/pnpm" + after_long_help = "Examples:\n\n $ aube prefix\n /home/user/project\n\n $ aube prefix -g\n /home/user/.local/share/pnpm", + effect = "read" )] pub struct PrefixArgs { /// Print the global prefix directory instead of the project's root @@ -2991,7 +3064,8 @@ pub struct PrefixArgs { #[derive(Args)] #[usage( - after_long_help = "Global store cleanup: use `aube store prune` to clean unreferenced files from the global\ncontent-addressable store." + after_long_help = "Global store cleanup: use `aube store prune` to clean unreferenced files from the global\ncontent-addressable store.", + effect = "write" )] pub struct PruneArgs { /// Remove devDependencies from node_modules @@ -3004,6 +3078,7 @@ pub struct PruneArgs { /// Publish the current package to the registry #[derive(Args)] +#[usage(effect = "write")] pub struct PublishArgs { #[usage( help = "Publish as `public` or `restricted`", @@ -3100,6 +3175,7 @@ pub struct PublishArgs { } #[derive(Args)] +#[usage(effect = "write")] pub struct PurgeArgs { #[usage( help = "Also remove lockfiles at the workspace root", @@ -3113,7 +3189,8 @@ pub struct PurgeArgs { /// Query packages in the resolved dependency graph #[derive(Args)] #[usage( - after_long_help = "Inspired by vlt's dependency selector model, but currently local-only:\nselectors read aube's lockfile graph without registry or security-service calls.\n\nExamples:\n\n # Every reachable package\n $ aube query '*'\n\n # Exact package name\n $ aube query '[name=react]'\n\n # Direct prod dependencies with install scripts\n $ aube query ':prod:scripts'\n\n # Local file/link/git/tarball dependencies\n $ aube query ':type(file), :type(link), :type(git), :type(remote)'\n\n # Machine-readable\n $ aube query ':bin' --json" + after_long_help = "Inspired by vlt's dependency selector model, but currently local-only:\nselectors read aube's lockfile graph without registry or security-service calls.\n\nExamples:\n\n # Every reachable package\n $ aube query '*'\n\n # Exact package name\n $ aube query '[name=react]'\n\n # Direct prod dependencies with install scripts\n $ aube query ':prod:scripts'\n\n # Local file/link/git/tarball dependencies\n $ aube query ':type(file), :type(link), :type(git), :type(remote)'\n\n # Machine-readable\n $ aube query ':bin' --json", + effect = "read" )] pub struct QueryArgs { /// Only match devDependency roots and their transitive deps @@ -3139,6 +3216,7 @@ pub struct QueryArgs { /// Re-run root lifecycle scripts and allowlisted dependency builds #[derive(Args)] +#[usage(effect = "write")] pub struct RebuildArgs { /// Optional package names. When supplied, only matching deps' scripts run; the root lifecycle hooks (preinstall, install, postinstall, prepare) are skipped. Match is by graph `name`, not by `dep_path`. The active `allowBuilds` / `onlyBuiltDependencies` policy is bypassed for the named deps — naming the package is the explicit opt-in #[usage(arg, name = "PACKAGE")] @@ -3155,6 +3233,7 @@ pub struct RecursiveArgs { /// Remove a dependency #[derive(Args)] +#[usage(effect = "destructive")] pub struct RemoveArgs { /// Remove only from devDependencies #[usage(long = "save-dev", short = 'D')] @@ -3321,7 +3400,8 @@ pub struct RestartArgs { /// Print the path to `node_modules` #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube root\n /home/user/project/node_modules\n\n $ aube root -g\n /home/user/.local/share/aube/global/node_modules" + after_long_help = "Examples:\n\n $ aube root\n /home/user/project/node_modules\n\n $ aube root -g\n /home/user/.local/share/aube/global/node_modules", + effect = "read" )] pub struct RootArgs { /// Print the global package directory instead of the project's @@ -3492,10 +3572,12 @@ pub struct RunArgs { /// Show the resolved runtime and installed versions #[derive(Args)] +#[usage(effect = "read")] pub struct RuntimeListArgs {} /// Pin a runtime in package.json devEngines.runtime and install it #[derive(Args)] +#[usage(effect = "write")] pub struct RuntimeSetArgs { /// Install for the user instead of the project (delegates to `mise use -g node@` when mise manages installs) #[usage(long = "global", short = 'g')] @@ -3516,6 +3598,7 @@ pub struct RuntimeSetArgs { /// Manage the project's Node.js runtime (pin, install, inspect) #[derive(Args)] +#[usage(effect = "read")] pub struct RuntimeArgs { #[usage(subcommand)] pub command: RuntimeCommands, @@ -3533,6 +3616,7 @@ pub enum RuntimeCommands { /// Generate a Software Bill of Materials (CycloneDX or SPDX) #[derive(Args)] +#[usage(effect = "read")] pub struct SbomArgs { /// Show only devDependencies #[usage(long = "dev", short = 'D')] @@ -3555,6 +3639,7 @@ pub struct SbomArgs { /// Search the registry for packages (not implemented — use `npm search`) #[derive(Args)] +#[usage(effect = "read")] pub struct SearchArgs { #[usage( help = "Number of retry attempts for failed registry fetches", @@ -3605,6 +3690,7 @@ pub struct SearchArgs { /// Alias for `config set` (hidden; prefer `config set`) #[derive(Args)] +#[usage(effect = "write")] pub struct SetArgs { /// Shortcut for `--location project` #[usage(long = "local")] @@ -3628,6 +3714,7 @@ pub struct SetArgs { /// Set a `package.json` script (not implemented — use `npm set-script`) #[derive(Args)] +#[usage(effect = "read")] pub struct SetScriptArgs { #[usage( help = "Number of retry attempts for failed registry fetches", @@ -3678,10 +3765,12 @@ pub struct SetScriptArgs { /// Show the companies sponsoring aube and the jdx.dev open source tools #[derive(Args)] +#[usage(effect = "read")] pub struct SponsorsArgs {} /// Stage packages for publishing (not implemented — use `npm stage`) #[derive(Args)] +#[usage(effect = "read")] pub struct StageArgs { #[usage( help = "Number of retry attempts for failed registry fetches", @@ -3883,6 +3972,7 @@ pub struct StopArgs { } #[derive(Args)] +#[usage(effect = "write")] pub struct StoreAddArgs { /// Package specs to fetch into the store #[usage(arg, name = "PACKAGES", required)] @@ -3891,16 +3981,20 @@ pub struct StoreAddArgs { /// Show the store path #[derive(Args)] +#[usage(effect = "read")] pub struct StorePathArgs {} #[derive(Args)] +#[usage(effect = "write")] pub struct StorePruneArgs {} #[derive(Args)] +#[usage(effect = "read")] pub struct StoreStatusArgs {} /// Manage the global store #[derive(Args)] +#[usage(effect = "read")] pub struct StoreArgs { #[usage(subcommand)] pub command: StoreCommands, @@ -4012,6 +4106,7 @@ pub struct TestArgs { /// Manage registry auth tokens (not implemented — use `npm token`) #[derive(Args)] +#[usage(effect = "read")] pub struct TokenArgs { #[usage( help = "Number of retry attempts for failed registry fetches", @@ -4063,7 +4158,8 @@ pub struct TokenArgs { /// Check one package version for a publishing-trust downgrade #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube trust check @hono/node-server@1.19.17\n @hono/node-server@1.19.17: pass\n published: 2026-07-27T03:07:48.993Z\n current evidence: trusted publisher\n strongest earlier evidence: trusted publisher (2.0.10)\n\n # Evaluate the underlying policy even when aube has a built-in exception\n $ aube trust check @hono/node-server@1.19.15 --ignore-default-excludes\n\n # Machine-readable report\n $ aube trust check @hono/node-server@1.19.17 --json" + after_long_help = "Examples:\n\n $ aube trust check @hono/node-server@1.19.17\n @hono/node-server@1.19.17: pass\n published: 2026-07-27T03:07:48.993Z\n current evidence: trusted publisher\n strongest earlier evidence: trusted publisher (2.0.10)\n\n # Evaluate the underlying policy even when aube has a built-in exception\n $ aube trust check @hono/node-server@1.19.15 --ignore-default-excludes\n\n # Machine-readable report\n $ aube trust check @hono/node-server@1.19.17 --json", + effect = "read" )] pub struct TrustCheckArgs { /// Evaluate the policy without aube's built-in package exceptions @@ -4123,6 +4219,7 @@ pub struct TrustCheckArgs { /// Inspect npm package publishing trust #[derive(Args)] +#[usage(effect = "read")] pub struct TrustArgs { #[usage(subcommand)] pub command: TrustCommands, @@ -4137,6 +4234,7 @@ pub enum TrustCommands { /// Clear an existing deprecation on the registry #[derive(Args)] +#[usage(effect = "write")] pub struct UndeprecateArgs { /// Don't PUT anything — print which versions would be touched and exit #[usage(long = "dry-run")] @@ -4197,6 +4295,7 @@ pub struct UndeprecateArgs { /// Unlink a package (remove linked entries from node_modules) #[derive(Args)] +#[usage(effect = "write")] pub struct UnlinkArgs { #[usage( help = "Operate on the global link registry instead of the current project", @@ -4212,6 +4311,7 @@ pub struct UnlinkArgs { /// Remove a package (or a single version) from the registry #[derive(Args)] +#[usage(effect = "destructive")] pub struct UnpublishArgs { /// Don't talk to the registry; print what the command would do #[usage(long = "dry-run")] @@ -4279,6 +4379,7 @@ pub struct UnpublishArgs { /// Update dependencies #[derive(Args)] +#[usage(effect = "write")] pub struct UpdateArgs { /// Update only devDependencies #[usage(long = "dev", short = 'D')] @@ -4436,6 +4537,7 @@ pub struct UpdateArgs { /// Bump the version in package.json (and optionally create a git commit + tag) #[derive(Args)] +#[usage(effect = "write")] pub struct VersionArgs { /// Allow setting the version to its current value without erroring #[usage(long = "allow-same-version")] @@ -4481,7 +4583,8 @@ pub struct VersionArgs { /// Print package metadata from the registry #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube view\n my-package@1.0.0 | MIT | deps: 0 | versions: 1\n\n $ aube view react\n react@18.3.1 | MIT | deps: 1 | versions: 2037\n React is a JavaScript library for building user interfaces.\n https://react.dev/\n\n keywords: react\n\n dist\n .tarball: https://registry.npmjs.org/react/-/react-18.3.1.tgz\n .shasum: a0b2eb79...\n .integrity: sha512-...\n\n # A specific version\n $ aube view react@17.0.2\n\n # A single field\n $ aube view react version\n 18.3.1\n\n $ aube view react dist.tarball\n https://registry.npmjs.org/react/-/react-18.3.1.tgz\n\n # All versions ever published\n $ aube view react versions --json\n\n # Raw JSON for the resolved version\n $ aube view react@next --json" + after_long_help = "Examples:\n\n $ aube view\n my-package@1.0.0 | MIT | deps: 0 | versions: 1\n\n $ aube view react\n react@18.3.1 | MIT | deps: 1 | versions: 2037\n React is a JavaScript library for building user interfaces.\n https://react.dev/\n\n keywords: react\n\n dist\n .tarball: https://registry.npmjs.org/react/-/react-18.3.1.tgz\n .shasum: a0b2eb79...\n .integrity: sha512-...\n\n # A specific version\n $ aube view react@17.0.2\n\n # A single field\n $ aube view react version\n 18.3.1\n\n $ aube view react dist.tarball\n https://registry.npmjs.org/react/-/react-18.3.1.tgz\n\n # All versions ever published\n $ aube view react versions --json\n\n # Raw JSON for the resolved version\n $ aube view react@next --json", + effect = "read" )] pub struct ViewArgs { #[usage( @@ -4550,6 +4653,7 @@ pub struct ViewArgs { /// Report the current registry user (not implemented — use `npm whoami`) #[derive(Args)] +#[usage(effect = "read")] pub struct WhoamiArgs { #[usage( help = "Number of retry attempts for failed registry fetches", @@ -4601,7 +4705,8 @@ pub struct WhoamiArgs { /// Print reverse dependency chains explaining why a package is installed #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ aube why debug\n my-app@1.0.0 /home/user/project\n\n dependencies:\n express 4.19.2\n └── debug 2.6.9\n body-parser 1.20.2\n └── debug 2.6.9\n\n # Only follow chains starting at a devDependency\n $ aube why --dev typescript\n\n # Include each node's store path\n $ aube why --long debug\n\n # Tab-separated, one chain per line (pipe-friendly)\n $ aube why --parseable debug\n\n # JSON: an array of chain objects\n $ aube why --json debug" + after_long_help = "Examples:\n\n $ aube why debug\n my-app@1.0.0 /home/user/project\n\n dependencies:\n express 4.19.2\n └── debug 2.6.9\n body-parser 1.20.2\n └── debug 2.6.9\n\n # Only follow chains starting at a devDependency\n $ aube why --dev typescript\n\n # Include each node's store path\n $ aube why --long debug\n\n # Tab-separated, one chain per line (pipe-friendly)\n $ aube why --parseable debug\n\n # JSON: an array of chain objects\n $ aube why --json debug", + effect = "read" )] pub struct WhyArgs { /// Only follow chains that start at a devDependency diff --git a/benches/shadows/communique/src/lib.rs b/benches/shadows/communique/src/lib.rs index 7419c50cf..372765796 100644 --- a/benches/shadows/communique/src/lib.rs +++ b/benches/shadows/communique/src/lib.rs @@ -9,12 +9,13 @@ use usage_derive::{Args, Cli, Subcommands}; /// Generate release notes for a git tag #[derive(Args)] +#[usage(effect = "read")] pub struct GenerateArgs { /// Push editorialized notes to the GitHub release - #[usage(long = "github-release")] + #[usage(long = "github-release", effect = "write")] pub github_release: bool, /// Update CHANGELOG.md with the generated changelog entry - #[usage(long = "changelog")] + #[usage(long = "changelog", effect = "write")] pub changelog: bool, /// Output concise changelog entry instead of detailed notes #[usage(long = "concise")] @@ -38,7 +39,7 @@ pub struct GenerateArgs { #[usage(long = "base-url", value_name = "BASE_URL")] pub base_url: ::std::option::Option<::std::string::String>, /// Write output to a file instead of stdout - #[usage(long = "output", short = 'o', value_name = "OUTPUT")] + #[usage(long = "output", short = 'o', effect = "write", value_name = "OUTPUT")] pub output: ::std::option::Option<::std::string::String>, /// Git tag to generate release notes for #[usage(arg, name = "TAG")] @@ -50,9 +51,10 @@ pub struct GenerateArgs { /// Generate a communique.toml config file in the repo root #[derive(Args)] +#[usage(effect = "write")] pub struct InitArgs { /// Overwrite existing config file - #[usage(long = "force")] + #[usage(long = "force", effect = "destructive")] pub force: bool, } @@ -64,6 +66,7 @@ pub struct SponsorsArgs {} /// /// https://usage.jdx.dev #[derive(Args)] +#[usage(effect = "read")] pub struct UsageArgs {} /// Editorialized release notes powered by AI diff --git a/benches/shadows/hk/src/lib.rs b/benches/shadows/hk/src/lib.rs index 6c97694ad..e8c999a33 100644 --- a/benches/shadows/hk/src/lib.rs +++ b/benches/shadows/hk/src/lib.rs @@ -9,6 +9,7 @@ use usage_derive::{Args, Cli, Subcommands}; /// Print a hook configuration for an agent or editor #[derive(Args)] +#[usage(effect = "read")] pub struct AgentHooksArgs { #[usage( long = "target", @@ -20,6 +21,7 @@ pub struct AgentHooksArgs { /// Print project instructions for a coding agent #[derive(Args)] +#[usage(effect = "read")] pub struct AgentInstructionsArgs { #[usage( long = "target", @@ -31,6 +33,7 @@ pub struct AgentInstructionsArgs { /// Print an MCP server configuration #[derive(Args)] +#[usage(effect = "read")] pub struct AgentMcpArgs { #[usage( long = "target", @@ -42,6 +45,7 @@ pub struct AgentMcpArgs { /// Generate integration snippets for coding agents #[derive(Args)] +#[usage(effect = "read")] pub struct AgentArgs { #[usage(subcommand)] pub command: AgentCommands, @@ -62,14 +66,17 @@ pub enum AgentCommands { /// Lists all available builtin linters #[derive(Args)] +#[usage(effect = "read")] pub struct BuiltinsArgs {} /// Clear the cache directory #[derive(Args)] +#[usage(effect = "write")] pub struct CacheClearArgs {} /// Manage hk internal cache #[derive(Args)] +#[usage(effect = "read")] pub struct CacheArgs { #[usage(subcommand)] pub command: CacheCommands, @@ -178,6 +185,7 @@ pub struct CheckArgs { /// Generates shell completion scripts #[derive(Args)] +#[usage(effect = "read")] pub struct CompletionArgs { /// The shell to generate completion for #[usage(arg, name = "SHELL")] @@ -188,6 +196,7 @@ pub struct CompletionArgs { /// /// Shows the merged configuration from all sources including CLI flags, environment variables, git config, user config, and project config. #[derive(Args)] +#[usage(effect = "read")] pub struct ConfigDumpArgs { /// Output format (json or toml) #[usage( @@ -203,6 +212,7 @@ pub struct ConfigDumpArgs { /// /// Shows the resolved value, its source (env/git/cli/default), and the full precedence chain showing all layers that could affect it. #[derive(Args)] +#[usage(effect = "read")] pub struct ConfigExplainArgs { /// Configuration key to explain #[usage(arg, name = "KEY")] @@ -213,6 +223,7 @@ pub struct ConfigExplainArgs { /// /// Available keys: jobs, enabled_profiles, disabled_profiles, fail_fast, display_skip_reasons, warnings, exclude, skip_steps, skip_hooks, stage #[derive(Args)] +#[usage(effect = "read")] pub struct ConfigGetArgs { /// Configuration key to retrieve /// @@ -225,12 +236,14 @@ pub struct ConfigGetArgs { /// /// Lists all configuration sources in order of precedence to help understand where configuration values come from. #[derive(Args)] +#[usage(effect = "read")] pub struct ConfigSourcesArgs {} /// Configuration introspection and management /// /// View and inspect hk's configuration from all sources. Configuration is merged from multiple sources in precedence order: CLI flags > Environment variables > Git config (local) > User config (.hkrc.pkl) > Git config (global) > Project config (hk.pkl) > Built-in defaults. #[derive(Args)] +#[usage(effect = "read")] pub struct ConfigArgs { #[usage(subcommand)] pub command: ::std::option::Option, @@ -348,6 +361,7 @@ pub struct FixArgs { /// Generates a new hk.pkl file for a project #[derive(Args)] +#[usage(effect = "write")] pub struct InitArgs { /// Overwrite existing hk.pkl file #[usage(long = "force", short = 'f')] @@ -363,6 +377,7 @@ pub struct InitArgs { } #[derive(Args)] +#[usage(effect = "write")] pub struct InstallArgs { #[usage( help = "Install local hooks even when hk is already configured globally\n(any `hook.hk-*` entry in `~/.gitconfig`). By default a per-repo\ninstall is skipped in that case to avoid hk firing twice per\nevent. Not compatible with `--global`.", @@ -397,6 +412,7 @@ pub struct McpArgs { /// Migrate from pre-commit to hk #[derive(Args)] +#[usage(effect = "write")] pub struct MigratePreCommitArgs { /// Path to .pre-commit-config.yaml #[usage( @@ -424,6 +440,7 @@ pub struct MigratePreCommitArgs { /// Migrate from other hook managers to hk #[derive(Args)] +#[usage(effect = "read")] pub struct MigrateArgs { #[usage(subcommand)] pub command: MigrateCommands, @@ -1436,6 +1453,7 @@ pub enum RunCommands { /// Show the companies sponsoring hk and the jdx.dev open source tools #[derive(Args)] +#[usage(effect = "read")] pub struct SponsorsArgs {} /// Run step-defined tests @@ -1454,6 +1472,7 @@ pub struct TestArgs { /// Removes hk hooks from the current git repository #[derive(Args)] +#[usage(effect = "destructive")] pub struct UninstallArgs { /// Remove hk hooks from the user's global git config (`~/.gitconfig`). #[usage(long = "global")] @@ -1464,10 +1483,12 @@ pub struct UninstallArgs { /// /// https://usage.jdx.dev #[derive(Args)] +#[usage(effect = "read")] pub struct UsageArgs {} /// Check for large files being added to repository #[derive(Args)] +#[usage(effect = "read")] pub struct UtilCheckAddedLargeFilesArgs { /// Maximum file size in kilobytes (default: 500) #[usage(long = "maxkb", value_name = "MAXKB", default = "500")] @@ -1479,6 +1500,7 @@ pub struct UtilCheckAddedLargeFilesArgs { /// Check for UTF-8 byte order marker (BOM) #[derive(Args)] +#[usage(effect = "read")] pub struct UtilCheckByteOrderMarkerArgs { /// Output a diff of the change #[usage(long = "diff", short = 'd')] @@ -1490,6 +1512,7 @@ pub struct UtilCheckByteOrderMarkerArgs { /// Check for case-insensitive filename conflicts #[derive(Args)] +#[usage(effect = "read")] pub struct UtilCheckCaseConflictArgs { /// Files to check for case conflicts #[usage(arg, name = "FILES", required)] @@ -1500,6 +1523,7 @@ pub struct UtilCheckCaseConflictArgs { /// /// Titles starting with `fixup! `, `squash! `, or `amend! ` (temporary commits created for `git rebase --autosquash`) skip validation. #[derive(Args)] +#[usage(effect = "read")] pub struct UtilCheckConventionalCommitArgs { #[usage( long = "allowed-types", @@ -1515,6 +1539,7 @@ pub struct UtilCheckConventionalCommitArgs { /// Check that executable files have shebangs #[derive(Args)] +#[usage(effect = "read")] pub struct UtilCheckExecutablesHaveShebangsArgs { /// Files to check #[usage(arg, name = "FILES", required)] @@ -1523,6 +1548,7 @@ pub struct UtilCheckExecutablesHaveShebangsArgs { /// Check for merge conflict markers #[derive(Args)] +#[usage(effect = "read")] pub struct UtilCheckMergeConflictArgs { /// Run the check even when not in a merge #[usage(long = "assume-in-merge")] @@ -1534,6 +1560,7 @@ pub struct UtilCheckMergeConflictArgs { /// Check for broken symlinks #[derive(Args)] +#[usage(effect = "read")] pub struct UtilCheckSymlinksArgs { /// Files to check #[usage(arg, name = "FILES", required)] @@ -1542,6 +1569,7 @@ pub struct UtilCheckSymlinksArgs { /// Detect private keys in files #[derive(Args)] +#[usage(effect = "read")] pub struct UtilDetectPrivateKeyArgs { /// Files to check #[usage(arg, name = "FILES", required)] @@ -1550,6 +1578,7 @@ pub struct UtilDetectPrivateKeyArgs { /// Check for and optionally fix missing final newlines #[derive(Args)] +#[usage(effect = "write")] pub struct UtilEndOfFileFixerArgs { /// Output a diff of the change. Cannot use with `fix` #[usage(long = "diff", short = 'd')] @@ -1564,6 +1593,7 @@ pub struct UtilEndOfFileFixerArgs { /// Remove UTF-8 byte order marker (BOM) #[derive(Args)] +#[usage(effect = "write")] pub struct UtilFixByteOrderMarkerArgs { /// Files to remove BOM from #[usage(arg, name = "FILES", required)] @@ -1572,6 +1602,7 @@ pub struct UtilFixByteOrderMarkerArgs { /// Replace UTF-8 smart quotes #[derive(Args)] +#[usage(effect = "write")] pub struct UtilFixSmartQuotesArgs { /// Check for smart quotes without fixing them #[usage(long = "check")] @@ -1586,6 +1617,7 @@ pub struct UtilFixSmartQuotesArgs { /// Detect and fix mixed line endings #[derive(Args)] +#[usage(effect = "write")] pub struct UtilMixedLineEndingArgs { /// Output a diff of the change. Cannot use with `fix` #[usage(long = "diff", short = 'd')] @@ -1600,6 +1632,7 @@ pub struct UtilMixedLineEndingArgs { /// Prevent commits to specific branches #[derive(Args)] +#[usage(effect = "read")] pub struct UtilNoCommitToBranchArgs { /// Branch names to protect (default: main, master) #[usage(long = "branch", value_name = "BRANCH", var)] @@ -1608,6 +1641,7 @@ pub struct UtilNoCommitToBranchArgs { /// Check Python files for valid syntax #[derive(Args)] +#[usage(effect = "read")] pub struct UtilPythonCheckAstArgs { /// Files to check #[usage(arg, name = "FILES", required)] @@ -1616,6 +1650,7 @@ pub struct UtilPythonCheckAstArgs { /// Detect Python debug statements #[derive(Args)] +#[usage(effect = "read")] pub struct UtilPythonDebugStatementsArgs { /// Files to check #[usage(arg, name = "FILES", required)] @@ -1624,6 +1659,7 @@ pub struct UtilPythonDebugStatementsArgs { /// Check for and optionally fix trailing whitespace #[derive(Args)] +#[usage(effect = "write")] pub struct UtilTrailingWhitespaceArgs { /// Output a diff of the change. Cannot use with `fix` #[usage(long = "diff", short = 'd')] @@ -1638,6 +1674,7 @@ pub struct UtilTrailingWhitespaceArgs { /// Utility commands for file operations #[derive(Args)] +#[usage(effect = "read")] pub struct UtilArgs { #[usage(subcommand)] pub command: UtilCommands, @@ -1697,10 +1734,12 @@ pub enum UtilCommands { /// Validate the config file #[derive(Args)] +#[usage(effect = "read")] pub struct ValidateArgs {} /// Print the version of hk #[derive(Args)] +#[usage(effect = "read")] pub struct VersionArgs {} /// A tool for managing git hooks diff --git a/benches/shadows/mise/src/lib.rs b/benches/shadows/mise/src/lib.rs index 84da930c8..745eb566d 100644 --- a/benches/shadows/mise/src/lib.rs +++ b/benches/shadows/mise/src/lib.rs @@ -25,7 +25,8 @@ use usage_derive::{Args, Cli, Subcommands}; /// Customize status output with `status` settings. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ eval \"$(mise activate bash)\"\n $ eval \"$(mise activate zsh)\"\n $ mise activate fish | source\n $ execx($(mise activate xonsh))\n $ (&mise activate pwsh) | Out-String | Invoke-Expression" + after_long_help = "Examples:\n\n $ eval \"$(mise activate bash)\"\n $ eval \"$(mise activate zsh)\"\n $ mise activate fish | source\n $ execx($(mise activate xonsh))\n $ (&mise activate pwsh) | Out-String | Invoke-Expression", + effect = "read" )] pub struct ActivateArgs { /// Suppress non-error messages @@ -67,7 +68,10 @@ pub struct ActivateArgs { /// /// This is the contents of a tool_alias. entry in ~/.config/mise/config.toml #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise tool-alias get node lts-hydrogen\n 20.0.0")] +#[usage( + after_long_help = "Examples:\n\n $ mise tool-alias get node lts-hydrogen\n 20.0.0", + effect = "read" +)] pub struct ToolAliasGetArgs { /// The tool to show the alias for #[usage(arg, name = "TOOL")] @@ -78,7 +82,10 @@ pub struct ToolAliasGetArgs { } #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise tool-alias ls\n node lts-jod 22")] +#[usage( + after_long_help = "Examples:\n\n $ mise tool-alias ls\n node lts-jod 22", + effect = "read" +)] pub struct ToolAliasLsArgs { /// Don't show table header #[usage(long = "no-header")] @@ -93,7 +100,8 @@ pub struct ToolAliasLsArgs { /// This modifies the contents of ~/.config/mise/config.toml #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise tool-alias set maven asdf:mise-plugins/mise-maven\n $ mise tool-alias set node lts-jod 22.0.0" + after_long_help = "Examples:\n\n $ mise tool-alias set maven asdf:mise-plugins/mise-maven\n $ mise tool-alias set node lts-jod 22.0.0", + effect = "write" )] pub struct ToolAliasSetArgs { /// The tool/backend to set the alias for @@ -112,7 +120,8 @@ pub struct ToolAliasSetArgs { /// This modifies the contents of ~/.config/mise/config.toml #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise tool-alias unset maven\n $ mise tool-alias unset node lts-jod" + after_long_help = "Examples:\n\n $ mise tool-alias unset maven\n $ mise tool-alias unset node lts-jod", + effect = "write" )] pub struct ToolAliasUnsetArgs { /// The tool/backend to remove the alias from @@ -125,6 +134,7 @@ pub struct ToolAliasUnsetArgs { /// Manage tool version aliases. #[derive(Args)] +#[usage(effect = "read")] pub struct ToolAliasArgs { /// Filter aliases by tool #[usage(long = "tool", short = 'p', value_name = "TOOL")] @@ -167,14 +177,16 @@ pub struct AsdfArgs { /// List built-in backends #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise backends ls\n aqua\n asdf\n cargo\n core\n dotnet\n gem\n go\n npm\n pipx\n spm\n ubi\n vfox" + after_long_help = "Examples:\n\n $ mise backends ls\n aqua\n asdf\n cargo\n core\n dotnet\n gem\n go\n npm\n pipx\n spm\n ubi\n vfox", + effect = "read" )] pub struct BackendsLsArgs {} /// Manage backends #[derive(Args)] #[usage( - after_long_help = "Deprecation:\n\nThe `mise b` alias is deprecated and will be removed in mise 2027.4.0.\nUse `mise backends` instead." + after_long_help = "Deprecation:\n\nThe `mise b` alias is deprecated and will be removed in mise 2027.4.0.\nUse `mise backends` instead.", + effect = "read" )] pub struct BackendsArgs { #[usage(subcommand)] @@ -190,6 +202,7 @@ pub enum BackendsCommands { /// List all the active runtime bin paths #[derive(Args)] +#[usage(effect = "read")] pub struct BinPathsArgs { /// Output executable names instead of bin directories #[usage(long = "bin-names")] @@ -202,25 +215,32 @@ pub struct BinPathsArgs { } #[derive(Args)] +#[usage(effect = "destructive")] pub struct BootstrapApplyAccountPlanArgs {} #[derive(Args)] +#[usage(effect = "destructive")] pub struct BootstrapApplyServicePlanArgs {} #[derive(Args)] +#[usage(effect = "destructive")] pub struct BootstrapApplyFirewallPlanArgs {} #[derive(Args)] +#[usage(effect = "destructive")] pub struct BootstrapApplySystemPlanArgs {} #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapInspectSystemFilesArgs {} #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapInspectFirewallPlanArgs {} /// Apply configured Linux users and groups #[derive(Args)] +#[usage(effect = "destructive")] pub struct BootstrapAccountsApplyArgs { /// Print what would change without changing anything #[usage(long = "dry-run", short = 'n')] @@ -232,6 +252,7 @@ pub struct BootstrapAccountsApplyArgs { /// Show configured Linux user and group state #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapAccountsStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -243,6 +264,7 @@ pub struct BootstrapAccountsStatusArgs { /// Manage Linux users and groups from `[bootstrap.users]` and `[bootstrap.groups]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapAccountsArgs { #[usage(subcommand)] pub command: BootstrapAccountsCommands, @@ -260,6 +282,7 @@ pub enum BootstrapAccountsCommands { /// Apply configured Docker Compose project state #[derive(Args)] +#[usage(effect = "destructive")] pub struct BootstrapComposeApplyArgs { /// Print what would change without changing anything #[usage(long = "dry-run", short = 'n')] @@ -271,6 +294,7 @@ pub struct BootstrapComposeApplyArgs { /// Show configured Docker Compose project state #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapComposeStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -282,6 +306,7 @@ pub struct BootstrapComposeStatusArgs { /// Manage Docker Compose projects from `[bootstrap.compose]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapComposeArgs { #[usage(subcommand)] pub command: BootstrapComposeCommands, @@ -304,7 +329,8 @@ pub enum BootstrapComposeCommands { /// under `dotfiles.root` unless `--source` is provided. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap dotfiles add ~/.zshrc\n $ mise bootstrap dotfiles add --mode copy ~/.config/starship.toml\n $ mise bootstrap dotfiles add --source dotfiles/gitconfig ~/.gitconfig" + after_long_help = "Examples:\n\n $ mise bootstrap dotfiles add ~/.zshrc\n $ mise bootstrap dotfiles add --mode copy ~/.config/starship.toml\n $ mise bootstrap dotfiles add --source dotfiles/gitconfig ~/.gitconfig", + effect = "write" )] pub struct BootstrapDotfilesAddArgs { /// Overwrite existing sources without prompting @@ -347,7 +373,8 @@ pub struct BootstrapDotfilesAddArgs { /// mise doesn't otherwise own. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap dotfiles apply\n $ mise bootstrap dotfiles apply --dry-run\n $ mise bootstrap dotfiles apply --force --yes" + after_long_help = "Examples:\n\n $ mise bootstrap dotfiles apply\n $ mise bootstrap dotfiles apply --dry-run\n $ mise bootstrap dotfiles apply --force --yes", + effect = "write" )] pub struct BootstrapDotfilesApplyArgs { /// Overwrite existing files that conflict with whole-file dotfile entries @@ -367,7 +394,8 @@ pub struct BootstrapDotfilesApplyArgs { /// Edit a managed dotfile source #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap dotfiles edit ~/.zshrc\n $ mise bootstrap dotfiles edit --apply ~/.config/starship.toml" + after_long_help = "Examples:\n\n $ mise bootstrap dotfiles edit ~/.zshrc\n $ mise bootstrap dotfiles edit --apply ~/.config/starship.toml", + effect = "write" )] pub struct BootstrapDotfilesEditArgs { /// Apply this target after the editor exits @@ -390,7 +418,8 @@ pub struct BootstrapDotfilesEditArgs { /// Show the status of dotfiles from `[dotfiles]` #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap dotfiles status\n $ mise bootstrap dotfiles status ~/.zshrc\n $ mise bootstrap dotfiles status --json\n $ mise bootstrap dotfiles status --missing # exit 1 if anything is out of sync" + after_long_help = "Examples:\n\n $ mise bootstrap dotfiles status\n $ mise bootstrap dotfiles status ~/.zshrc\n $ mise bootstrap dotfiles status --json\n $ mise bootstrap dotfiles status --missing # exit 1 if anything is out of sync", + effect = "read" )] pub struct BootstrapDotfilesStatusArgs { /// Output in JSON format @@ -413,7 +442,8 @@ pub struct BootstrapDotfilesStatusArgs { /// edits require `--force`. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap dotfiles unapply\n $ mise bootstrap dotfiles unapply ~/.zshrc\n $ mise bootstrap dotfiles unapply --dry-run\n $ mise bootstrap dotfiles unapply --force --yes" + after_long_help = "Examples:\n\n $ mise bootstrap dotfiles unapply\n $ mise bootstrap dotfiles unapply ~/.zshrc\n $ mise bootstrap dotfiles unapply --dry-run\n $ mise bootstrap dotfiles unapply --force --yes", + effect = "destructive" )] pub struct BootstrapDotfilesUnapplyArgs { /// Remove modified or otherwise ambiguous managed files and lines @@ -432,6 +462,7 @@ pub struct BootstrapDotfilesUnapplyArgs { /// Manage dotfiles from `[dotfiles]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapDotfilesArgs { #[usage(subcommand)] pub command: BootstrapDotfilesCommands, @@ -458,6 +489,7 @@ pub enum BootstrapDotfilesCommands { /// Apply configured privileged files and directories #[derive(Args)] +#[usage(effect = "destructive")] pub struct BootstrapFilesApplyArgs { /// Print what would change without changing anything #[usage(long = "dry-run", short = 'n')] @@ -472,6 +504,7 @@ pub struct BootstrapFilesApplyArgs { /// Show configured privileged file and directory state #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapFilesStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -486,6 +519,7 @@ pub struct BootstrapFilesStatusArgs { /// Manage privileged files and directories from `[bootstrap.files]` and `[bootstrap.directories]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapFilesArgs { #[usage(subcommand)] pub command: BootstrapFilesCommands, @@ -503,6 +537,7 @@ pub enum BootstrapFilesCommands { /// Apply the configured Linux host firewall #[derive(Args)] +#[usage(effect = "destructive")] pub struct BootstrapFirewallApplyArgs { /// Print what would change without changing anything #[usage(long = "dry-run", short = 'n')] @@ -514,6 +549,7 @@ pub struct BootstrapFirewallApplyArgs { /// Show configured Linux host firewall state #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapFirewallStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -525,6 +561,7 @@ pub struct BootstrapFirewallStatusArgs { /// Manage the Linux host firewall from `[bootstrap.linux.firewall]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapFirewallArgs { #[usage(subcommand)] pub command: BootstrapFirewallCommands, @@ -541,6 +578,7 @@ pub enum BootstrapFirewallCommands { } #[derive(Args)] +#[usage(effect = "write")] pub struct BootstrapLaunchdApplyArgs { /// Print the commands that would run without running them #[usage(long = "dry-run", short = 'n')] @@ -551,6 +589,7 @@ pub struct BootstrapLaunchdApplyArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapLaunchdStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -562,6 +601,7 @@ pub struct BootstrapLaunchdStatusArgs { /// Manage macOS LaunchAgents from `[bootstrap.macos.launchd.agents]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapLaunchdArgs { #[usage(subcommand)] pub command: BootstrapLaunchdCommands, @@ -576,6 +616,7 @@ pub enum BootstrapLaunchdCommands { } #[derive(Args)] +#[usage(effect = "write")] pub struct BootstrapLinuxSystemdUnitsApplyArgs { /// Print the commands that would run without running them #[usage(long = "dry-run", short = 'n')] @@ -586,6 +627,7 @@ pub struct BootstrapLinuxSystemdUnitsApplyArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapLinuxSystemdUnitsStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -597,6 +639,7 @@ pub struct BootstrapLinuxSystemdUnitsStatusArgs { /// Manage systemd user services from `[bootstrap.linux.systemd.units]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapLinuxSystemdUnitsArgs { #[usage(subcommand)] pub command: BootstrapLinuxSystemdUnitsCommands, @@ -612,6 +655,7 @@ pub enum BootstrapLinuxSystemdUnitsCommands { /// Manage Linux bootstrap config from `[bootstrap.linux]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapLinuxArgs { #[usage(subcommand)] pub command: BootstrapLinuxCommands, @@ -625,6 +669,7 @@ pub enum BootstrapLinuxCommands { } #[derive(Args)] +#[usage(effect = "write")] pub struct BootstrapMacosDefaultsApplyArgs { /// Print the commands that would run without running them #[usage(long = "dry-run", short = 'n')] @@ -635,6 +680,7 @@ pub struct BootstrapMacosDefaultsApplyArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapMacosDefaultsStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -646,6 +692,7 @@ pub struct BootstrapMacosDefaultsStatusArgs { /// Manage macOS defaults from `[bootstrap.macos.defaults]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapMacosDefaultsArgs2 { #[usage(subcommand)] pub command: BootstrapMacosDefaultsCommands2, @@ -660,6 +707,7 @@ pub enum BootstrapMacosDefaultsCommands2 { } #[derive(Args)] +#[usage(effect = "write")] pub struct BootstrapMacosLaunchdAgentsApplyArgs { /// Print the commands that would run without running them #[usage(long = "dry-run", short = 'n')] @@ -670,6 +718,7 @@ pub struct BootstrapMacosLaunchdAgentsApplyArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapMacosLaunchdAgentsStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -681,6 +730,7 @@ pub struct BootstrapMacosLaunchdAgentsStatusArgs { /// Manage macOS LaunchAgents from `[bootstrap.macos.launchd.agents]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapMacosLaunchdAgentsArgs { #[usage(subcommand)] pub command: BootstrapMacosLaunchdAgentsCommands, @@ -696,6 +746,7 @@ pub enum BootstrapMacosLaunchdAgentsCommands { /// Manage macOS bootstrap config from `[bootstrap.macos]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapMacosArgs { #[usage(subcommand)] pub command: BootstrapMacosCommands, @@ -712,6 +763,7 @@ pub enum BootstrapMacosCommands { } #[derive(Args)] +#[usage(effect = "write")] pub struct BootstrapMacosDefaultsApplyArgs2 { /// Print the commands that would run without running them #[usage(long = "dry-run", short = 'n')] @@ -722,6 +774,7 @@ pub struct BootstrapMacosDefaultsApplyArgs2 { } #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapMacosDefaultsStatusArgs2 { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -733,6 +786,7 @@ pub struct BootstrapMacosDefaultsStatusArgs2 { /// Manage macOS defaults from `[bootstrap.macos.defaults]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapMacosDefaultsArgs { #[usage(subcommand)] pub command: BootstrapMacosDefaultsCommands, @@ -747,6 +801,7 @@ pub enum BootstrapMacosDefaultsCommands { } #[derive(Args)] +#[usage(effect = "write")] pub struct BootstrapMiseShellActivateApplyArgs { /// Print the actions that would run without writing anything #[usage(long = "dry-run", short = 'n')] @@ -757,6 +812,7 @@ pub struct BootstrapMiseShellActivateApplyArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapMiseShellActivateStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -768,6 +824,7 @@ pub struct BootstrapMiseShellActivateStatusArgs { /// Manage mise shell activation from `[bootstrap.mise_shell_activate]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapMiseShellActivateArgs { #[usage(subcommand)] pub command: BootstrapMiseShellActivateCommands, @@ -793,7 +850,8 @@ pub enum BootstrapMiseShellActivateCommands { /// only. `install` is accepted as an alias for this command. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap packages apply\n $ mise bootstrap packages apply apk:zlib-dev apt:curl brew:jq brew-cask:firefox flatpak:org.mozilla.firefox mas:497799835\n $ mise bootstrap packages apply --dry-run\n $ mise bootstrap packages apply --manager apt --yes" + after_long_help = "Examples:\n\n $ mise bootstrap packages apply\n $ mise bootstrap packages apply apk:zlib-dev apt:curl brew:jq brew-cask:firefox flatpak:org.mozilla.firefox mas:497799835\n $ mise bootstrap packages apply --dry-run\n $ mise bootstrap packages apply --manager apt --yes", + effect = "write" )] pub struct BootstrapPackagesApplyArgs { /// Only install packages for this built-in or plugin manager @@ -816,7 +874,8 @@ pub struct BootstrapPackagesApplyArgs { /// Add a Homebrew tap URL to [bootstrap.brew.taps] #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap packages brew tap railwaycat/emacsmacport\n $ mise bootstrap packages brew tap acme/tools https://github.com/acme/homebrew-tools.git" + after_long_help = "Examples:\n\n $ mise bootstrap packages brew tap railwaycat/emacsmacport\n $ mise bootstrap packages brew tap acme/tools https://github.com/acme/homebrew-tools.git", + effect = "write" )] pub struct BootstrapPackagesBrewTapArgs { /// Write to the local config instead of the global config @@ -839,7 +898,8 @@ pub struct BootstrapPackagesBrewTapArgs { /// Remove Homebrew tap URLs from [bootstrap.brew.taps] #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap packages brew untap railwaycat/emacsmacport" + after_long_help = "Examples:\n\n $ mise bootstrap packages brew untap railwaycat/emacsmacport", + effect = "write" )] pub struct BootstrapPackagesBrewUntapArgs { /// Write to the local config instead of the global config @@ -861,6 +921,7 @@ pub struct BootstrapPackagesBrewUntapArgs { /// These commands edit `[bootstrap.brew.taps]` so tapped formulae and casks /// can be fetched directly by mise without a Homebrew installation. #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapPackagesBrewArgs { #[usage(subcommand)] pub command: BootstrapPackagesBrewCommands, @@ -883,7 +944,8 @@ pub enum BootstrapPackagesBrewCommands { /// Pass `--all` to import every linked formula, including dependencies. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap packages import --manager brew\n $ mise bootstrap packages import --manager brew --all\n $ mise bootstrap packages import --manager brew --global\n $ mise bootstrap packages import --manager brew --dry-run" + after_long_help = "Examples:\n\n $ mise bootstrap packages import --manager brew\n $ mise bootstrap packages import --manager brew --all\n $ mise bootstrap packages import --manager brew --global\n $ mise bootstrap packages import --manager brew --dry-run", + effect = "write" )] pub struct BootstrapPackagesImportArgs { /// Write to the config file for this environment (mise..toml) @@ -919,7 +981,8 @@ pub struct BootstrapPackagesImportArgs { /// configs. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap packages prune --manager brew\n $ mise bootstrap packages prune --manager brew --dry-run\n $ mise bootstrap packages prune --manager brew --yes" + after_long_help = "Examples:\n\n $ mise bootstrap packages prune --manager brew\n $ mise bootstrap packages prune --manager brew --dry-run\n $ mise bootstrap packages prune --manager brew --yes", + effect = "destructive" )] pub struct BootstrapPackagesPruneArgs { /// Only prune packages for this manager. Currently only `brew` is supported @@ -942,7 +1005,8 @@ pub struct BootstrapPackagesPruneArgs { /// Show the status of system packages from `[bootstrap.packages]` #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap packages status\n $ mise bootstrap packages status --json\n $ mise bootstrap packages status --missing # exit 1 if anything is out of sync" + after_long_help = "Examples:\n\n $ mise bootstrap packages status\n $ mise bootstrap packages status --json\n $ mise bootstrap packages status --missing # exit 1 if anything is out of sync", + effect = "read" )] pub struct BootstrapPackagesStatusArgs { /// Output in JSON format @@ -966,7 +1030,8 @@ pub struct BootstrapPackagesStatusArgs { /// Packages can also be given explicitly in `manager:package` form. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap packages upgrade\n $ mise bootstrap packages upgrade brew:postgresql@17\n $ mise bootstrap packages upgrade --manager brew-cask\n $ mise bootstrap packages upgrade --manager mas\n $ mise bootstrap packages upgrade --manager apt --yes\n $ mise bootstrap packages upgrade --dry-run" + after_long_help = "Examples:\n\n $ mise bootstrap packages upgrade\n $ mise bootstrap packages upgrade brew:postgresql@17\n $ mise bootstrap packages upgrade --manager brew-cask\n $ mise bootstrap packages upgrade --manager mas\n $ mise bootstrap packages upgrade --manager apt --yes\n $ mise bootstrap packages upgrade --dry-run", + effect = "write" )] pub struct BootstrapPackagesUpgradeArgs { /// Only upgrade packages for this built-in or plugin manager @@ -996,7 +1061,8 @@ pub struct BootstrapPackagesUpgradeArgs { /// a mise version selector. mas uses numeric ADAM IDs and does not support pins. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap packages use apk:zlib-dev apt:curl brew:jq brew-cask:firefox flatpak:org.mozilla.firefox mas:497799835\n $ mise bootstrap packages use -g brew:postgresql@17\n $ mise bootstrap packages use apt:curl@8.5.0-2" + after_long_help = "Examples:\n\n $ mise bootstrap packages use apk:zlib-dev apt:curl brew:jq brew-cask:firefox flatpak:org.mozilla.firefox mas:497799835\n $ mise bootstrap packages use -g brew:postgresql@17\n $ mise bootstrap packages use apt:curl@8.5.0-2", + effect = "write" )] pub struct BootstrapPackagesUseArgs { /// Write to the config file for this environment (mise..toml) @@ -1021,6 +1087,7 @@ pub struct BootstrapPackagesUseArgs { /// Manage bootstrap system packages from `[bootstrap.packages]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapPackagesArgs { #[usage(subcommand)] pub command: BootstrapPackagesCommands, @@ -1053,6 +1120,7 @@ pub enum BootstrapPackagesCommands { /// Show the changes declarative bootstrap resources would make #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapPlanArgs { /// Output a stable machine-readable plan in JSON format #[usage(long = "json", short = 'J')] @@ -1066,6 +1134,7 @@ pub struct BootstrapPlanArgs { } #[derive(Args)] +#[usage(effect = "write")] pub struct BootstrapPluginsApplyArgs { /// Print what would happen without installing plugins #[usage(long = "dry-run", short = 'n')] @@ -1073,6 +1142,7 @@ pub struct BootstrapPluginsApplyArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapPluginsStatusArgs { /// Exit with code 1 if a declared plugin is missing #[usage(long = "missing")] @@ -1081,6 +1151,7 @@ pub struct BootstrapPluginsStatusArgs { /// Manage package manager plugins declared in `[bootstrap.plugins]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapPluginsArgs { #[usage(subcommand)] pub command: BootstrapPluginsCommands, @@ -1096,6 +1167,7 @@ pub enum BootstrapPluginsCommands { /// Bootstrap one or more machines over OpenSSH #[derive(Args)] +#[usage(effect = "destructive")] pub struct BootstrapRemoteArgs { /// Select every configured inventory host #[usage(long = "all")] @@ -1224,6 +1296,7 @@ pub struct BootstrapRemoteArgs { } #[derive(Args)] +#[usage(effect = "write")] pub struct BootstrapReposApplyArgs { /// Print the commands that would run without running them #[usage(long = "dry-run", short = 'n')] @@ -1250,6 +1323,7 @@ pub struct BootstrapReposExecArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapReposStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -1260,6 +1334,7 @@ pub struct BootstrapReposStatusArgs { } #[derive(Args)] +#[usage(effect = "write")] pub struct BootstrapReposUpdateArgs { /// Print the commands that would run without running them #[usage(long = "dry-run", short = 'n')] @@ -1274,6 +1349,7 @@ pub struct BootstrapReposUpdateArgs { /// Manage git repo checkouts from `[bootstrap.repos]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapReposArgs { #[usage(subcommand)] pub command: BootstrapReposCommands, @@ -1293,6 +1369,7 @@ pub enum BootstrapReposCommands { /// Show whether declared bootstrap secret inputs are available #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapSecretsStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -1304,6 +1381,7 @@ pub struct BootstrapSecretsStatusArgs { /// Inspect bootstrap secret inputs without revealing their values #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapSecretsArgs { #[usage(subcommand)] pub command: BootstrapSecretsCommands, @@ -1318,6 +1396,7 @@ pub enum BootstrapSecretsCommands { /// Apply configured Linux system service state #[derive(Args)] +#[usage(effect = "destructive")] pub struct BootstrapServicesApplyArgs { /// Print what would change without changing anything #[usage(long = "dry-run", short = 'n')] @@ -1329,6 +1408,7 @@ pub struct BootstrapServicesApplyArgs { /// Show configured Linux system service state #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapServicesStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -1340,6 +1420,7 @@ pub struct BootstrapServicesStatusArgs { /// Manage Linux system services from `[bootstrap.services]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapServicesArgs { #[usage(subcommand)] pub command: BootstrapServicesCommands, @@ -1357,6 +1438,7 @@ pub enum BootstrapServicesCommands { /// Show the aggregate bootstrap status #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -1370,6 +1452,7 @@ pub struct BootstrapStatusArgs { } #[derive(Args)] +#[usage(effect = "write")] pub struct BootstrapSystemdApplyArgs { /// Print the commands that would run without running them #[usage(long = "dry-run", short = 'n')] @@ -1380,6 +1463,7 @@ pub struct BootstrapSystemdApplyArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapSystemdStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -1391,6 +1475,7 @@ pub struct BootstrapSystemdStatusArgs { /// Manage systemd user services from `[bootstrap.linux.systemd.units]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapSystemdArgs { #[usage(subcommand)] pub command: BootstrapSystemdCommands, @@ -1405,6 +1490,7 @@ pub enum BootstrapSystemdCommands { } #[derive(Args)] +#[usage(effect = "write")] pub struct BootstrapUserApplyArgs { /// Print the commands that would run without running them #[usage(long = "dry-run", short = 'n')] @@ -1415,6 +1501,7 @@ pub struct BootstrapUserApplyArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapUserStatusArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -1426,6 +1513,7 @@ pub struct BootstrapUserStatusArgs { /// Manage current-user bootstrap settings from `[bootstrap.user]` #[derive(Args)] +#[usage(effect = "read")] pub struct BootstrapUserArgs { #[usage(subcommand)] pub command: BootstrapUserCommands, @@ -1490,7 +1578,8 @@ pub enum BootstrapUserCommands { /// cannot be used together. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap # packages + repos + dotfiles + tools + bootstrap task\n $ mise bootstrap --force-dotfiles # replace conflicting dotfile targets\n $ mise bootstrap --skip tools,task # skip tool installation and the bootstrap task\n $ mise bootstrap --only tools # run just tool installation\n $ mise bootstrap status --missing\n $ mise bootstrap packages apply --yes\n $ mise bootstrap repos status\n $ mise bootstrap repos apply --dry-run\n $ mise bootstrap dotfiles status\n $ mise bootstrap mise-shell-activate apply --dry-run\n $ mise bootstrap macos defaults status\n $ mise bootstrap macos launchd-agents apply --dry-run\n $ mise bootstrap linux systemd-units apply --dry-run\n $ mise bootstrap user apply --dry-run" + after_long_help = "Examples:\n\n $ mise bootstrap # packages + repos + dotfiles + tools + bootstrap task\n $ mise bootstrap --force-dotfiles # replace conflicting dotfile targets\n $ mise bootstrap --skip tools,task # skip tool installation and the bootstrap task\n $ mise bootstrap --only tools # run just tool installation\n $ mise bootstrap status --missing\n $ mise bootstrap packages apply --yes\n $ mise bootstrap repos status\n $ mise bootstrap repos apply --dry-run\n $ mise bootstrap dotfiles status\n $ mise bootstrap mise-shell-activate apply --dry-run\n $ mise bootstrap macos defaults status\n $ mise bootstrap macos launchd-agents apply --dry-run\n $ mise bootstrap linux systemd-units apply --dry-run\n $ mise bootstrap user apply --dry-run", + effect = "destructive" )] pub struct BootstrapArgs { /// Print what would happen without installing anything @@ -1654,6 +1743,7 @@ pub enum BootstrapCommands { /// Deletes all cache files in mise #[derive(Args)] +#[usage(effect = "write")] pub struct CacheClearArgs { /// Mark all cache files as old #[usage(long = "outdate", hide)] @@ -1668,6 +1758,7 @@ pub struct CacheClearArgs { /// Show the cache directory path #[derive(Args)] +#[usage(effect = "read")] pub struct CachePathArgs {} /// Removes stale mise cache files @@ -1675,6 +1766,7 @@ pub struct CachePathArgs {} /// By default, this command will remove files that have not been accessed in 30 days. /// Change this with the MISE_CACHE_PRUNE_AGE environment variable. #[derive(Args)] +#[usage(effect = "write")] pub struct CachePruneArgs { /// Show pruned files #[usage(long = "verbose", short = 'v', count)] @@ -1689,6 +1781,7 @@ pub struct CachePruneArgs { /// Inspect output cache entries for a task #[derive(Args)] +#[usage(effect = "read")] pub struct CacheTaskArgs { /// Output in JSON format #[usage(long = "json", short = 'J')] @@ -1702,6 +1795,7 @@ pub struct CacheTaskArgs { /// /// Run `mise cache` with no args to view the current cache directory. #[derive(Args)] +#[usage(effect = "read")] pub struct CacheArgs { #[usage(subcommand)] pub command: ::std::option::Option, @@ -1726,7 +1820,8 @@ pub enum CacheCommands { /// Generate shell completions #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise completion bash --include-bash-completion-lib > ~/.local/share/bash-completion/completions/mise\n $ mise completion zsh > /usr/local/share/zsh/site-functions/_mise\n $ mise completion fish > ~/.config/fish/completions/mise.fish\n $ mise completion powershell >> $PROFILE" + after_long_help = "Examples:\n\n $ mise completion bash --include-bash-completion-lib > ~/.local/share/bash-completion/completions/mise\n $ mise completion zsh > /usr/local/share/zsh/site-functions/_mise\n $ mise completion fish > ~/.config/fish/completions/mise.fish\n $ mise completion powershell >> $PROFILE", + effect = "read" )] pub struct CompletionArgs { /// Shell type to generate completions for @@ -1758,7 +1853,10 @@ pub struct CompletionArgs { /// Display the value of a setting in a mise.toml file #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise toml get tools.python\n 3.12")] +#[usage( + after_long_help = "Examples:\n\n $ mise toml get tools.python\n 3.12", + effect = "read" +)] pub struct ConfigGetArgs { /// The path to the mise.toml file to read /// @@ -1775,7 +1873,8 @@ pub struct ConfigGetArgs { /// List config files currently in use #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise config ls\n Path Tools\n ~/.config/mise/config.toml pitchfork\n ~/src/mise/mise.toml actionlint, bun, cargo-binstall, cargo:cargo-insta" + after_long_help = "Examples:\n\n $ mise config ls\n Path Tools\n ~/.config/mise/config.toml pitchfork\n ~/src/mise/mise.toml actionlint, bun, cargo-binstall, cargo:cargo-insta", + effect = "read" )] pub struct ConfigLsArgs { /// Output in JSON format @@ -1792,7 +1891,8 @@ pub struct ConfigLsArgs { /// Set the value of a setting in a mise.toml file #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise config set tools.python 3.12\n $ mise config set settings.always_keep_download true\n $ mise config set env.TEST_ENV_VAR ABC\n $ mise config set settings.disable_tools node,rust\n\n # Type for `settings` is inferred\n $ mise config set settings.jobs 4" + after_long_help = "Examples:\n\n $ mise config set tools.python 3.12\n $ mise config set settings.always_keep_download true\n $ mise config set env.TEST_ENV_VAR ABC\n $ mise config set settings.disable_tools node,rust\n\n # Type for `settings` is inferred\n $ mise config set settings.jobs 4", + effect = "write" )] pub struct ConfigSetArgs { /// The path to the mise.toml file to edit @@ -1821,7 +1921,8 @@ pub struct ConfigSetArgs { /// Manage config files #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise config ls\n Path Tools\n ~/.config/mise/config.toml pitchfork\n ~/src/mise/mise.toml actionlint, bun, cargo-binstall, cargo:cargo-insta" + after_long_help = "Examples:\n\n $ mise config ls\n Path Tools\n ~/.config/mise/config.toml pitchfork\n ~/src/mise/mise.toml actionlint, bun, cargo-binstall, cargo:cargo-insta", + effect = "read" )] pub struct ConfigArgs { /// Output in JSON format @@ -1856,7 +1957,8 @@ pub enum ConfigCommands { /// and/or version. It's designed to fit into scripts more easily. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # outputs `.tool-versions` compatible format\n $ mise current\n python 3.11.0 3.10.0\n shfmt 3.6.0\n shellcheck 0.9.0\n node 20.0.0\n\n $ mise current node\n 20.0.0\n\n # can output multiple versions\n $ mise current python\n 3.11.0 3.10.0" + after_long_help = "Examples:\n\n # outputs `.tool-versions` compatible format\n $ mise current\n python 3.11.0 3.10.0\n shfmt 3.6.0\n shellcheck 0.9.0\n node 20.0.0\n\n $ mise current node\n 20.0.0\n\n # can output multiple versions\n $ mise current python\n 3.11.0 3.10.0", + effect = "read" )] pub struct CurrentArgs { /// Plugin to show versions of e.g.: ruby, node, cargo:eza, npm:prettier, etc @@ -1868,7 +1970,10 @@ pub struct CurrentArgs { /// /// This can be used to temporarily disable mise in a shell session. #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise deactivate")] +#[usage( + after_long_help = "Examples:\n\n $ mise deactivate", + effect = "read" +)] pub struct DeactivateArgs {} /// Output direnv function to use mise inside direnv @@ -1880,11 +1985,13 @@ pub struct DeactivateArgs {} /// direnv may not know to update environment variables when idiomatic file versions change. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise direnv activate > ~/.config/direnv/lib/use_mise.sh\n $ echo 'use mise' > .envrc\n $ direnv allow" + after_long_help = "Examples:\n\n $ mise direnv activate > ~/.config/direnv/lib/use_mise.sh\n $ echo 'use mise' > .envrc\n $ direnv allow", + effect = "read" )] pub struct DirenvActivateArgs {} #[derive(Args)] +#[usage(effect = "write")] pub struct DirenvEnvrcArgs {} #[derive(Args)] @@ -1898,6 +2005,7 @@ pub struct DirenvExecArgs {} /// you should run this command after installing new plugins. Otherwise /// direnv may not know to update environment variables when idiomatic file versions change. #[derive(Args)] +#[usage(effect = "read")] pub struct DirenvArgs { #[usage(subcommand)] pub command: ::std::option::Option, @@ -1929,7 +2037,8 @@ pub enum DirenvCommands { /// under `dotfiles.root` unless `--source` is provided. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap dotfiles add ~/.zshrc\n $ mise bootstrap dotfiles add --mode copy ~/.config/starship.toml\n $ mise bootstrap dotfiles add --source dotfiles/gitconfig ~/.gitconfig" + after_long_help = "Examples:\n\n $ mise bootstrap dotfiles add ~/.zshrc\n $ mise bootstrap dotfiles add --mode copy ~/.config/starship.toml\n $ mise bootstrap dotfiles add --source dotfiles/gitconfig ~/.gitconfig", + effect = "write" )] pub struct DotfilesAddArgs { /// Overwrite existing sources without prompting @@ -1972,7 +2081,8 @@ pub struct DotfilesAddArgs { /// mise doesn't otherwise own. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap dotfiles apply\n $ mise bootstrap dotfiles apply --dry-run\n $ mise bootstrap dotfiles apply --force --yes" + after_long_help = "Examples:\n\n $ mise bootstrap dotfiles apply\n $ mise bootstrap dotfiles apply --dry-run\n $ mise bootstrap dotfiles apply --force --yes", + effect = "write" )] pub struct DotfilesApplyArgs { /// Overwrite existing files that conflict with whole-file dotfile entries @@ -1992,7 +2102,8 @@ pub struct DotfilesApplyArgs { /// Edit a managed dotfile source #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap dotfiles edit ~/.zshrc\n $ mise bootstrap dotfiles edit --apply ~/.config/starship.toml" + after_long_help = "Examples:\n\n $ mise bootstrap dotfiles edit ~/.zshrc\n $ mise bootstrap dotfiles edit --apply ~/.config/starship.toml", + effect = "write" )] pub struct DotfilesEditArgs { /// Apply this target after the editor exits @@ -2015,7 +2126,8 @@ pub struct DotfilesEditArgs { /// Show the status of dotfiles from `[dotfiles]` #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap dotfiles status\n $ mise bootstrap dotfiles status ~/.zshrc\n $ mise bootstrap dotfiles status --json\n $ mise bootstrap dotfiles status --missing # exit 1 if anything is out of sync" + after_long_help = "Examples:\n\n $ mise bootstrap dotfiles status\n $ mise bootstrap dotfiles status ~/.zshrc\n $ mise bootstrap dotfiles status --json\n $ mise bootstrap dotfiles status --missing # exit 1 if anything is out of sync", + effect = "read" )] pub struct DotfilesStatusArgs { /// Output in JSON format @@ -2038,7 +2150,8 @@ pub struct DotfilesStatusArgs { /// edits require `--force`. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise bootstrap dotfiles unapply\n $ mise bootstrap dotfiles unapply ~/.zshrc\n $ mise bootstrap dotfiles unapply --dry-run\n $ mise bootstrap dotfiles unapply --force --yes" + after_long_help = "Examples:\n\n $ mise bootstrap dotfiles unapply\n $ mise bootstrap dotfiles unapply ~/.zshrc\n $ mise bootstrap dotfiles unapply --dry-run\n $ mise bootstrap dotfiles unapply --force --yes", + effect = "destructive" )] pub struct DotfilesUnapplyArgs { /// Remove modified or otherwise ambiguous managed files and lines @@ -2059,6 +2172,7 @@ pub struct DotfilesUnapplyArgs { /// /// Use `mise bootstrap dotfiles` instead. #[derive(Args)] +#[usage(effect = "read")] pub struct DotfilesArgs { #[usage(subcommand)] pub command: DotfilesCommands, @@ -2086,7 +2200,8 @@ pub enum DotfilesCommands { /// Print the current PATH entries mise is providing #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n Get the current PATH entries mise is providing\n $ mise doctor path\n /home/user/.local/share/mise/installs/node/24.0.0/bin\n /home/user/.local/share/mise/installs/rust/1.90.0/bin\n /home/user/.local/share/mise/installs/python/3.10.0/bin" + after_long_help = "Examples:\n\n Get the current PATH entries mise is providing\n $ mise doctor path\n /home/user/.local/share/mise/installs/node/24.0.0/bin\n /home/user/.local/share/mise/installs/rust/1.90.0/bin\n /home/user/.local/share/mise/installs/python/3.10.0/bin", + effect = "read" )] pub struct DoctorPathArgs { /// Print all entries including those not provided by mise @@ -2097,7 +2212,8 @@ pub struct DoctorPathArgs { /// Check mise installation for possible problems #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise doctor\n [WARN] plugin node is not installed" + after_long_help = "Examples:\n\n $ mise doctor\n [WARN] plugin node is not installed", + effect = "read" )] pub struct DoctorArgs { #[usage(long = "json", short = 'J')] @@ -2139,7 +2255,8 @@ pub struct EnArgs { /// use this if you have `mise activate` in your shell rc file. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ eval \"$(mise env -s bash)\"\n $ eval \"$(mise env -s zsh)\"\n $ mise env -s fish | source\n $ execx($(mise env -s xonsh))" + after_long_help = "Examples:\n\n $ eval \"$(mise env -s bash)\"\n $ eval \"$(mise env -s zsh)\"\n $ mise env -s fish | source\n $ execx($(mise env -s xonsh))", + effect = "read" )] pub struct EnvArgs { /// Output in dotenv format @@ -2250,7 +2367,7 @@ pub struct ExecArgs { /// /// Sorts keys and cleans up whitespace in mise.toml #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise fmt")] +#[usage(after_long_help = "Examples:\n\n $ mise fmt", effect = "write")] pub struct FmtArgs { /// Format all files from the current directory #[usage(long = "all", short = 'a')] @@ -2268,7 +2385,8 @@ pub struct FmtArgs { /// This is designed to be used in a project where contributors may not have mise installed. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise generate bootstrap >./bin/mise\n $ chmod +x ./bin/mise\n $ ./bin/mise install – automatically downloads mise to .mise if not already installed" + after_long_help = "Examples:\n\n $ mise generate bootstrap >./bin/mise\n $ chmod +x ./bin/mise\n $ ./bin/mise install – automatically downloads mise to .mise if not already installed", + effect = "write" )] pub struct GenerateBootstrapArgs { /// Sandboxes mise internal directories like MISE_DATA_DIR and MISE_CACHE_DIR into a `.mise` directory in the project @@ -2294,7 +2412,8 @@ pub struct GenerateBootstrapArgs { /// Generate a mise.toml file #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise generate config # generate mise.toml interactively\n $ mise generate config .mise.toml # generate a specific file\n $ mise generate config -g # generate the global config file\n $ mise generate config -y # skip interactive editor\n $ mise generate config -n # preview without writing" + after_long_help = "Examples:\n\n $ mise generate config # generate mise.toml interactively\n $ mise generate config .mise.toml # generate a specific file\n $ mise generate config -g # generate the global config file\n $ mise generate config -y # skip interactive editor\n $ mise generate config -n # preview without writing", + effect = "write" )] pub struct GenerateConfigArgs { /// Generate the global config file (~/.config/mise/config.toml) @@ -2313,7 +2432,10 @@ pub struct GenerateConfigArgs { /// Generate a devcontainer to execute mise #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise generate devcontainer")] +#[usage( + after_long_help = "Examples:\n\n $ mise generate devcontainer", + effect = "write" +)] pub struct GenerateDevcontainerArgs { /// The image to use for the devcontainer #[usage(long = "image", short = 'i', value_name = "IMAGE")] @@ -2339,7 +2461,8 @@ pub struct GenerateDevcontainerArgs { /// For more advanced pre-commit functionality, see mise's sister project: https://hk.jdx.dev/ #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise generate git-pre-commit --write --task=pre-commit\n $ git commit -m \"feat: add new feature\" # runs `mise run pre-commit`" + after_long_help = "Examples:\n\n $ mise generate git-pre-commit --write --task=pre-commit\n $ git commit -m \"feat: add new feature\" # runs `mise run pre-commit`", + effect = "write" )] pub struct GenerateGitPreCommitArgs { /// The task to run when the pre-commit hook is triggered @@ -2364,7 +2487,8 @@ pub struct GenerateGitPreCommitArgs { /// when you push changes to your repository. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise generate github-action --write --task=ci\n $ git commit -m \"feat: add new feature\"\n $ git push # runs `mise run ci` on GitHub" + after_long_help = "Examples:\n\n $ mise generate github-action --write --task=ci\n $ git commit -m \"feat: add new feature\"\n $ git push # runs `mise run ci` on GitHub", + effect = "write" )] pub struct GenerateGithubActionArgs { /// The task to run when the workflow is triggered @@ -2380,7 +2504,10 @@ pub struct GenerateGithubActionArgs { /// Generate documentation for tasks in a project #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise generate task-docs")] +#[usage( + after_long_help = "Examples:\n\n $ mise generate task-docs", + effect = "write" +)] pub struct GenerateTaskDocsArgs { /// inserts the documentation into an existing file /// @@ -2418,7 +2545,8 @@ pub struct GenerateTaskDocsArgs { /// so contributors to a project can execute mise tasks without installing mise into their system. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise tasks add test -- echo 'running tests'\n $ mise generate task-stubs\n $ ./bin/test\n running tests" + after_long_help = "Examples:\n\n $ mise tasks add test -- echo 'running tests'\n $ mise generate task-stubs\n $ ./bin/test\n running tests", + effect = "write" )] pub struct GenerateTaskStubsArgs { /// Directory to create task stubs inside of @@ -2447,7 +2575,8 @@ pub struct GenerateTaskStubsArgs { /// to incrementally build cross-platform tool stubs. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n Generate a tool stub for a single URL:\n $ mise generate tool-stub ./bin/gh --url \"https://github.com/cli/cli/releases/download/v2.96.0/gh_2.96.0_linux_amd64.tar.gz\"\n\n Generate a tool stub with platform-specific URLs:\n $ mise generate tool-stub ./bin/rg \\\n --platform-url linux-x64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-x86_64-unknown-linux-musl.tar.gz \\\n --platform-url darwin-arm64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-aarch64-apple-darwin.tar.gz\n\n Append additional platforms to an existing stub:\n $ mise generate tool-stub ./bin/rg \\\n --platform-url linux-x64:https://example.com/rg-linux.tar.gz\n $ mise generate tool-stub ./bin/rg \\\n --platform-url darwin-arm64:https://example.com/rg-darwin.tar.gz\n # The stub now contains both platforms\n\n Use auto-detection for platform from URL:\n $ mise generate tool-stub ./bin/node \\\n --platform-url https://nodejs.org/dist/v22.17.1/node-v22.17.1-darwin-arm64.tar.gz\n # Platform 'macos-arm64' will be auto-detected from the URL\n\n Generate with platform-specific binary paths:\n $ mise generate tool-stub ./bin/tool \\\n --platform-url linux-x64:https://example.com/tool-linux.tar.gz \\\n --platform-url windows-x64:https://example.com/tool-windows.zip \\\n --platform-bin windows-x64:tool.exe\n\n Generate without downloading (faster):\n $ mise generate tool-stub ./bin/tool --url \"https://example.com/tool.tar.gz\" --skip-download\n\n Fetch checksums for an existing stub:\n $ mise generate tool-stub ./bin/jq --fetch\n # This will read the existing stub and download files to fill in any missing checksums/sizes\n\n Generate a bootstrap stub that installs mise if needed:\n $ mise generate tool-stub ./bin/tool --url \"https://example.com/tool.tar.gz\" --bootstrap\n # The stub will check for mise and install it automatically before running the tool\n\n Generate a bootstrap stub with a pinned mise version:\n $ mise generate tool-stub ./bin/tool --url \"https://example.com/tool.tar.gz\" --bootstrap --bootstrap-version 2025.1.0\n\n Lock an existing tool stub with pinned version and platform URLs/checksums:\n $ mise generate tool-stub ./bin/node --lock\n\n Bump the version in a locked stub:\n $ mise generate tool-stub ./bin/node --lock --version 22\n # Resolves the latest node 22.x, pins it, and updates platform URLs/checksums" + after_long_help = "Examples:\n\n Generate a tool stub for a single URL:\n $ mise generate tool-stub ./bin/gh --url \"https://github.com/cli/cli/releases/download/v2.96.0/gh_2.96.0_linux_amd64.tar.gz\"\n\n Generate a tool stub with platform-specific URLs:\n $ mise generate tool-stub ./bin/rg \\\n --platform-url linux-x64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-x86_64-unknown-linux-musl.tar.gz \\\n --platform-url darwin-arm64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-aarch64-apple-darwin.tar.gz\n\n Append additional platforms to an existing stub:\n $ mise generate tool-stub ./bin/rg \\\n --platform-url linux-x64:https://example.com/rg-linux.tar.gz\n $ mise generate tool-stub ./bin/rg \\\n --platform-url darwin-arm64:https://example.com/rg-darwin.tar.gz\n # The stub now contains both platforms\n\n Use auto-detection for platform from URL:\n $ mise generate tool-stub ./bin/node \\\n --platform-url https://nodejs.org/dist/v22.17.1/node-v22.17.1-darwin-arm64.tar.gz\n # Platform 'macos-arm64' will be auto-detected from the URL\n\n Generate with platform-specific binary paths:\n $ mise generate tool-stub ./bin/tool \\\n --platform-url linux-x64:https://example.com/tool-linux.tar.gz \\\n --platform-url windows-x64:https://example.com/tool-windows.zip \\\n --platform-bin windows-x64:tool.exe\n\n Generate without downloading (faster):\n $ mise generate tool-stub ./bin/tool --url \"https://example.com/tool.tar.gz\" --skip-download\n\n Fetch checksums for an existing stub:\n $ mise generate tool-stub ./bin/jq --fetch\n # This will read the existing stub and download files to fill in any missing checksums/sizes\n\n Generate a bootstrap stub that installs mise if needed:\n $ mise generate tool-stub ./bin/tool --url \"https://example.com/tool.tar.gz\" --bootstrap\n # The stub will check for mise and install it automatically before running the tool\n\n Generate a bootstrap stub with a pinned mise version:\n $ mise generate tool-stub ./bin/tool --url \"https://example.com/tool.tar.gz\" --bootstrap --bootstrap-version 2025.1.0\n\n Lock an existing tool stub with pinned version and platform URLs/checksums:\n $ mise generate tool-stub ./bin/node --lock\n\n Bump the version in a locked stub:\n $ mise generate tool-stub ./bin/node --lock --version 22\n # Resolves the latest node 22.x, pins it, and updates platform URLs/checksums", + effect = "write" )] pub struct GenerateToolStubArgs { /// Binary path within the extracted archive @@ -2512,6 +2641,7 @@ pub struct GenerateToolStubArgs { /// Generate files for various tools/services #[derive(Args)] +#[usage(effect = "read")] pub struct GenerateArgs { #[usage(subcommand)] pub command: GenerateCommands, @@ -2551,7 +2681,8 @@ pub enum GenerateCommands { /// authentication issues. The token is masked by default. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise github token\n github.com: ghp_…xxxx (source: GITHUB_TOKEN)\n\n $ mise github token --unmask\n github.com: ghp_xxxxxxxxxxxx (source: GITHUB_TOKEN)\n\n $ mise github token github.mycompany.com\n github.mycompany.com: (none)" + after_long_help = "Examples:\n\n $ mise github token\n github.com: ghp_…xxxx (source: GITHUB_TOKEN)\n\n $ mise github token --unmask\n github.com: ghp_xxxxxxxxxxxx (source: GITHUB_TOKEN)\n\n $ mise github token github.mycompany.com\n github.mycompany.com: (none)", + effect = "read" )] pub struct GithubTokenArgs { /// Force native GitHub OAuth device flow instead of normal token resolution @@ -2573,6 +2704,7 @@ pub struct GithubTokenArgs { /// GitHub related commands #[derive(Args)] +#[usage(effect = "read")] pub struct GithubArgs { #[usage(subcommand)] pub command: GithubCommands, @@ -2597,7 +2729,8 @@ pub enum GithubCommands { /// Use `mise local` to set a tool version locally in the current directory. #[derive(Args)] #[usage( - after_long_help = "Examples:\n # set the current version of node to 20.x\n # will use a fuzzy version (e.g.: 20) in .tool-versions file\n $ mise global --fuzzy node@20\n\n # set the current version of node to 20.x\n # will use a precise version (e.g.: 20.0.0) in .tool-versions file\n $ mise global --pin node@20\n\n # show the current version of node in ~/.tool-versions\n $ mise global node\n 20.0.0" + after_long_help = "Examples:\n # set the current version of node to 20.x\n # will use a fuzzy version (e.g.: 20) in .tool-versions file\n $ mise global --fuzzy node@20\n\n # set the current version of node to 20.x\n # will use a precise version (e.g.: 20.0.0) in .tool-versions file\n $ mise global --pin node@20\n\n # show the current version of node in ~/.tool-versions\n $ mise global node\n 20.0.0", + effect = "write" )] pub struct GlobalArgs { #[usage( @@ -2626,6 +2759,7 @@ pub struct GlobalArgs { /// [internal] called by activate hook to update env vars directory change #[derive(Args)] +#[usage(effect = "read")] pub struct HookEnvArgs { /// Skip early exit check #[usage(long = "force", short = 'f')] @@ -2656,6 +2790,7 @@ pub struct HookEnvArgs { /// [internal] called by shell when a command is not found #[derive(Args)] +#[usage(effect = "write")] pub struct HookNotFoundArgs { /// Shell type to generate script for #[usage( @@ -2674,6 +2809,7 @@ pub struct HookNotFoundArgs { /// /// Skips config directory by default. #[derive(Args)] +#[usage(effect = "destructive")] pub struct ImplodeArgs { /// List directories that would be removed without actually removing them #[usage(long = "dry-run", short = 'n')] @@ -2686,7 +2822,8 @@ pub struct ImplodeArgs { /// Edit mise.toml interactively #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise edit # edit mise.toml interactively\n $ mise edit .mise.toml # edit a specific file\n $ mise edit -g # edit the global config file\n $ mise edit -y # skip interactive editor\n $ mise edit -n # preview without writing" + after_long_help = "Examples:\n\n $ mise edit # edit mise.toml interactively\n $ mise edit .mise.toml # edit a specific file\n $ mise edit -g # edit the global config file\n $ mise edit -y # skip interactive editor\n $ mise edit -n # preview without writing", + effect = "write" )] pub struct EditArgs { /// Edit the global config file (~/.config/mise/config.toml) @@ -2714,7 +2851,8 @@ pub struct EditArgs { /// Tools will be installed in parallel. To disable, set `--jobs=1` or `MISE_JOBS=1` #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise install node@20.0.0 # install specific node version\n $ mise install node@20 # install fuzzy node version\n $ mise install node # install version specified in mise.toml\n $ mise install # installs everything specified in mise.toml" + after_long_help = "Examples:\n\n $ mise install node@20.0.0 # install specific node version\n $ mise install node@20 # install fuzzy node version\n $ mise install node # install version specified in mise.toml\n $ mise install # installs everything specified in mise.toml", + effect = "write" )] pub struct InstallArgs { /// Force reinstall even if already installed @@ -2776,7 +2914,8 @@ pub struct InstallArgs { /// Used for building a tool to a directory for use outside of mise #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # install node@20.0.0 into ./mynode\n $ mise install-into node@20.0.0 ./mynode && ./mynode/bin/node -v\n 20.0.0" + after_long_help = "Examples:\n\n # install node@20.0.0 into ./mynode\n $ mise install-into node@20.0.0 ./mynode && ./mynode/bin/node -v\n 20.0.0", + effect = "write" )] pub struct InstallIntoArgs { /// Tool to install e.g.: node@20 @@ -2792,7 +2931,8 @@ pub struct InstallIntoArgs { /// Supports prefixes such as `node@20` to get the latest version of node 20. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise latest node@20 # get the latest version of node 20\n 20.0.0\n\n $ mise latest node # get the latest stable version of node\n 20.0.0\n\n $ mise latest node --minimum-release-age 2024-01-01 # latest stable node released before 2024-01-01" + after_long_help = "Examples:\n\n $ mise latest node@20 # get the latest version of node 20\n 20.0.0\n\n $ mise latest node # get the latest stable version of node\n 20.0.0\n\n $ mise latest node --minimum-release-age 2024-01-01 # latest stable node released before 2024-01-01", + effect = "read" )] pub struct LatestArgs { /// Show latest installed instead of available version @@ -2817,7 +2957,8 @@ pub struct LatestArgs { /// Use this for adding installs either custom compiled outside mise or built with a different tool. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # build node-20.0.0 with node-build and link it into mise\n $ node-build 20.0.0 ~/.nodes/20.0.0\n $ mise link node@20.0.0 ~/.nodes/20.0.0\n\n # have mise use the node version provided by Homebrew\n $ brew install node\n $ mise link node@brew $(brew --prefix node)\n $ mise use node@brew" + after_long_help = "Examples:\n\n # build node-20.0.0 with node-build and link it into mise\n $ node-build 20.0.0 ~/.nodes/20.0.0\n $ mise link node@20.0.0 ~/.nodes/20.0.0\n\n # have mise use the node version provided by Homebrew\n $ brew install node\n $ mise link node@brew $(brew --prefix node)\n $ mise use node@brew", + effect = "write" )] pub struct LinkArgs { /// Overwrite an existing tool version if it exists @@ -2842,7 +2983,8 @@ pub struct LinkArgs { /// is set. A future v2 release of mise will default to using `mise.toml`. #[derive(Args)] #[usage( - after_long_help = "Examples:\n # set the current version of node to 20.x for the current directory\n # will use a precise version (e.g.: 20.0.0) in .tool-versions file\n $ mise local node@20\n\n # set node to 20.x for the current project (recurses up to find .tool-versions)\n $ mise local -p node@20\n\n # set the current version of node to 20.x for the current directory\n # will use a fuzzy version (e.g.: 20) in .tool-versions file\n $ mise local --fuzzy node@20\n\n # removes node from .tool-versions\n $ mise local --remove=node\n\n # show the current version of node in .tool-versions\n $ mise local node\n 20.0.0" + after_long_help = "Examples:\n # set the current version of node to 20.x for the current directory\n # will use a precise version (e.g.: 20.0.0) in .tool-versions file\n $ mise local node@20\n\n # set node to 20.x for the current project (recurses up to find .tool-versions)\n $ mise local -p node@20\n\n # set the current version of node to 20.x for the current directory\n # will use a fuzzy version (e.g.: 20) in .tool-versions file\n $ mise local --fuzzy node@20\n\n # removes node from .tool-versions\n $ mise local --remove=node\n\n # show the current version of node in .tool-versions\n $ mise local node\n 20.0.0", + effect = "write" )] pub struct LocalArgs { #[usage( @@ -2881,7 +3023,8 @@ pub struct LocalArgs { /// Operates on the lockfile in the current config root. Use TOOL arguments to target specific tools. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise lock # update lockfile for all common platforms\n $ mise lock node python # update only node and python\n $ mise lock --platform linux-x64 # update only linux-x64 platform\n $ mise lock --dry-run # show what would be updated\n $ mise lock --bump # re-resolve selectors like \"latest\" or \"20\" to the latest matching versions\n $ mise lock --bump --dry-run --json # list available updates as JSON without writing\n $ mise lock --minimum-release-age 2024-01-01 # lock latest/fuzzy versions released before 2024-01-01\n $ mise lock --local # update mise.local.lock for local configs\n $ mise lock --global # update only global config lockfiles" + after_long_help = "Examples:\n\n $ mise lock # update lockfile for all common platforms\n $ mise lock node python # update only node and python\n $ mise lock --platform linux-x64 # update only linux-x64 platform\n $ mise lock --dry-run # show what would be updated\n $ mise lock --bump # re-resolve selectors like \"latest\" or \"20\" to the latest matching versions\n $ mise lock --bump --dry-run --json # list available updates as JSON without writing\n $ mise lock --minimum-release-age 2024-01-01 # lock latest/fuzzy versions released before 2024-01-01\n $ mise lock --local # update mise.local.lock for local configs\n $ mise lock --global # update only global config lockfiles", + effect = "write" )] pub struct LockArgs { #[usage( @@ -2956,7 +3099,8 @@ pub struct LockArgs { /// It's a useful command to get the current state of your tools. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise ls\n node 20.0.0 ~/src/myapp/.tool-versions latest\n python 3.11.0 ~/.tool-versions 3.10\n python 3.10.0\n\n $ mise ls --current\n node 20.0.0 ~/src/myapp/.tool-versions 20\n python 3.11.0 ~/.tool-versions 3.11.0\n\n $ mise ls --json\n {\n \"node\": [\n {\n \"version\": \"20.0.0\",\n \"install_path\": \"/Users/jdx/.mise/installs/node/20.0.0\",\n \"source\": {\n \"type\": \"mise.toml\",\n \"path\": \"/Users/jdx/mise.toml\"\n }\n }\n ],\n \"python\": [...]\n }\n\n $ mise ls --all-sources\n node 20.0.0 ~/src/myapp/mise.toml 20\n ~/.config/mise/config.toml latest" + after_long_help = "Examples:\n\n $ mise ls\n node 20.0.0 ~/src/myapp/.tool-versions latest\n python 3.11.0 ~/.tool-versions 3.10\n python 3.10.0\n\n $ mise ls --current\n node 20.0.0 ~/src/myapp/.tool-versions 20\n python 3.11.0 ~/.tool-versions 3.11.0\n\n $ mise ls --json\n {\n \"node\": [\n {\n \"version\": \"20.0.0\",\n \"install_path\": \"/Users/jdx/.mise/installs/node/20.0.0\",\n \"source\": {\n \"type\": \"mise.toml\",\n \"path\": \"/Users/jdx/mise.toml\"\n }\n }\n ],\n \"python\": [...]\n }\n\n $ mise ls --all-sources\n node 20.0.0 ~/src/myapp/mise.toml 20\n ~/.config/mise/config.toml latest", + effect = "read" )] pub struct LsArgs { /// Only show tool versions currently specified in a mise.toml @@ -3013,7 +3157,8 @@ pub struct LsArgs { /// Note that the results may be cached, run `mise cache clean` to clear the cache and get fresh results. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise ls-remote node\n 18.0.0\n 20.0.0\n\n $ mise ls-remote node@20\n 20.0.0\n 20.1.0\n\n $ mise ls-remote node 20\n 20.0.0\n 20.1.0\n\n $ mise ls-remote node --minimum-release-age 2024-01-01\n 20.0.0\n\n $ mise ls-remote github:cli/cli --json\n [{\"version\":\"2.62.0\",\"created_at\":\"2024-11-14T15:40:35Z\",\"prerelease\":false},{\"version\":\"2.61.0\",\"created_at\":\"2024-10-23T19:22:15Z\",\"prerelease\":false}]" + after_long_help = "Examples:\n\n $ mise ls-remote node\n 18.0.0\n 20.0.0\n\n $ mise ls-remote node@20\n 20.0.0\n 20.1.0\n\n $ mise ls-remote node 20\n 20.0.0\n 20.1.0\n\n $ mise ls-remote node --minimum-release-age 2024-01-01\n 20.0.0\n\n $ mise ls-remote github:cli/cli --json\n [{\"version\":\"2.62.0\",\"created_at\":\"2024-11-14T15:40:35Z\",\"prerelease\":false},{\"version\":\"2.61.0\",\"created_at\":\"2024-10-23T19:22:15Z\",\"prerelease\":false}]", + effect = "read" )] pub struct LsRemoteArgs { /// Show all installed plugins and versions @@ -3096,7 +3241,8 @@ pub struct McpArgs {} /// Requires `mise settings experimental=true` (or `MISE_EXPERIMENTAL=1`). #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n Build with defaults (debian:bookworm-slim base):\n $ mise oci build\n\n Build with a specific base image and tag:\n $ mise oci build --from ubuntu:24.04 --tag myorg/dev:latest -o ./img\n\n Inspect the result with skopeo:\n $ skopeo inspect oci:./mise-oci\n\n Push to a registry:\n $ mise oci push --image-dir ./mise-oci ghcr.io/me/dev:latest\n\nNotes:\n\n - The image only contains tools from the project's mise config (and\n any configs at-or-below the project root). Tools from\n `~/.config/mise/config.toml` are not included; pass --include-global\n to package them too.\n - asdf and vfox plugins are not supported in v1; use a different backend\n (core, aqua, ubi, github, cargo, npm, go, pipx, spm, http) for each tool.\n - The host mise binary is embedded at /usr/local/bin/mise by default;\n build on the same OS/arch as your target image (or pass --no-mise)." + after_long_help = "Examples:\n\n Build with defaults (debian:bookworm-slim base):\n $ mise oci build\n\n Build with a specific base image and tag:\n $ mise oci build --from ubuntu:24.04 --tag myorg/dev:latest -o ./img\n\n Inspect the result with skopeo:\n $ skopeo inspect oci:./mise-oci\n\n Push to a registry:\n $ mise oci push --image-dir ./mise-oci ghcr.io/me/dev:latest\n\nNotes:\n\n - The image only contains tools from the project's mise config (and\n any configs at-or-below the project root). Tools from\n `~/.config/mise/config.toml` are not included; pass --include-global\n to package them too.\n - asdf and vfox plugins are not supported in v1; use a different backend\n (core, aqua, ubi, github, cargo, npm, go, pipx, spm, http) for each tool.\n - The host mise binary is embedded at /usr/local/bin/mise by default;\n build on the same OS/arch as your target image (or pass --no-mise).", + effect = "write" )] pub struct OciBuildArgs { /// Copy a host file, directory, or symlink into the image (repeatable, HOST:IMAGE) @@ -3155,7 +3301,8 @@ pub struct OciBuildArgs { /// Requires `mise settings experimental=true` (or `MISE_EXPERIMENTAL=1`). #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n Build and push to GHCR:\n $ mise oci push ghcr.io/me/devenv:latest\n\n Push an image built earlier:\n $ mise oci build -o ./img\n $ mise oci push --image-dir ./img ghcr.io/me/devenv:v1\n\nAuth:\n\n Credentials are resolved the same way docker/podman resolve them:\n $REGISTRY_AUTH_FILE, $XDG_RUNTIME_DIR/containers/auth.json,\n ~/.config/containers/auth.json, then ~/.docker/config.json\n (inline auths and credential helpers). Log in with either:\n $ docker login ghcr.io\n $ podman login ghcr.io" + after_long_help = "Examples:\n\n Build and push to GHCR:\n $ mise oci push ghcr.io/me/devenv:latest\n\n Push an image built earlier:\n $ mise oci build -o ./img\n $ mise oci push --image-dir ./img ghcr.io/me/devenv:v1\n\nAuth:\n\n Credentials are resolved the same way docker/podman resolve them:\n $REGISTRY_AUTH_FILE, $XDG_RUNTIME_DIR/containers/auth.json,\n ~/.config/containers/auth.json, then ~/.docker/config.json\n (inline auths and credential helpers). Log in with either:\n $ docker login ghcr.io\n $ podman login ghcr.io", + effect = "write" )] pub struct OciPushArgs { /// Reuse unchanged tool layers from this image instead of the destination ref @@ -3279,6 +3426,7 @@ pub struct OciRunArgs { /// (or `MISE_EXPERIMENTAL=1`). Behavior, flags, and output layout may change /// in future releases. #[derive(Args)] +#[usage(effect = "read")] pub struct OciArgs { #[usage(subcommand)] pub command: OciCommands, @@ -3302,7 +3450,8 @@ pub enum OciCommands { /// See `mise upgrade` to upgrade these versions. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise outdated\n Plugin Requested Current Latest\n python 3.11 3.11.0 3.11.1\n node 20 20.0.0 20.1.0\n\n $ mise outdated node\n Plugin Requested Current Latest\n node 20 20.0.0 20.1.0\n\n $ mise outdated --json\n {\"python\": {\"requested\": \"3.11\", \"current\": \"3.11.0\", \"latest\": \"3.11.1\"}, ...}\n\n $ mise outdated --local\n Plugin Requested Current Latest\n node 20 20.0.0 20.1.0" + after_long_help = "Examples:\n\n $ mise outdated\n Plugin Requested Current Latest\n python 3.11 3.11.0 3.11.1\n node 20 20.0.0 20.1.0\n\n $ mise outdated node\n Plugin Requested Current Latest\n node 20 20.0.0 20.1.0\n\n $ mise outdated --json\n {\"python\": {\"requested\": \"3.11\", \"current\": \"3.11.0\", \"latest\": \"3.11.1\"}, ...}\n\n $ mise outdated --local\n Plugin Requested Current Latest\n node 20 20.0.0 20.1.0", + effect = "read" )] pub struct OutdatedArgs { /// Output in JSON format @@ -3350,7 +3499,8 @@ pub struct OutdatedArgs { /// To appear here, become a patron at . #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise patrons\n $ mise patrons -J\n $ mise patrons --refresh" + after_long_help = "Examples:\n\n $ mise patrons\n $ mise patrons -J\n $ mise patrons --refresh", + effect = "read" )] pub struct PatronsArgs { /// Output in JSON format @@ -3369,7 +3519,8 @@ pub struct PatronsArgs { /// This behavior can be modified in ~/.config/mise/config.toml #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # install the poetry via shorthand\n $ mise plugins install poetry\n\n # install the poetry plugin using a specific git url\n $ mise plugins install poetry https://github.com/mise-plugins/mise-poetry.git\n\n # install the poetry plugin using the git url only\n # (poetry is inferred from the url)\n $ mise plugins install https://github.com/mise-plugins/mise-poetry.git\n\n # install the poetry plugin using a specific ref\n $ mise plugins install poetry https://github.com/mise-plugins/mise-poetry.git#11d0c1e" + after_long_help = "Examples:\n\n # install the poetry via shorthand\n $ mise plugins install poetry\n\n # install the poetry plugin using a specific git url\n $ mise plugins install poetry https://github.com/mise-plugins/mise-poetry.git\n\n # install the poetry plugin using the git url only\n # (poetry is inferred from the url)\n $ mise plugins install https://github.com/mise-plugins/mise-poetry.git\n\n # install the poetry plugin using a specific ref\n $ mise plugins install poetry https://github.com/mise-plugins/mise-poetry.git#11d0c1e", + effect = "write" )] pub struct PluginsInstallArgs { #[usage( @@ -3405,7 +3556,8 @@ pub struct PluginsInstallArgs { /// This is used for developing a plugin. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # essentially just `ln -s ./vfox-cmake ~/.local/share/mise/plugins/cmake`\n $ mise plugins link cmake ./vfox-cmake\n\n # infer plugin name as \"cmake\"\n $ mise plugins link ./vfox-cmake" + after_long_help = "Examples:\n\n # essentially just `ln -s ./vfox-cmake ~/.local/share/mise/plugins/cmake`\n $ mise plugins link cmake ./vfox-cmake\n\n # infer plugin name as \"cmake\"\n $ mise plugins link ./vfox-cmake", + effect = "write" )] pub struct PluginsLinkArgs { /// Overwrite existing plugin @@ -3430,7 +3582,8 @@ pub struct PluginsLinkArgs { /// Can also show remotely available plugins to install. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise plugins ls\n cmake\n poetry\n\n $ mise plugins ls --urls\n cmake https://github.com/mise-plugins/vfox-cmake.git\n poetry https://github.com/mise-plugins/vfox-poetry.git" + after_long_help = "Examples:\n\n $ mise plugins ls\n cmake\n poetry\n\n $ mise plugins ls --urls\n cmake https://github.com/mise-plugins/vfox-cmake.git\n poetry https://github.com/mise-plugins/vfox-poetry.git", + effect = "read" )] pub struct PluginsLsArgs { #[usage( @@ -3471,6 +3624,7 @@ pub struct PluginsLsArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct PluginsLsRemoteArgs { /// Show the git url for each plugin e.g.: https://github.com/mise-plugins/mise-poetry.git #[usage(long = "urls", short = 'u')] @@ -3482,7 +3636,10 @@ pub struct PluginsLsRemoteArgs { /// Removes a plugin #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise plugins uninstall cmake")] +#[usage( + after_long_help = "Examples:\n\n $ mise plugins uninstall cmake", + effect = "destructive" +)] pub struct PluginsUninstallArgs { /// Remove all plugins #[usage(long = "all", short = 'a')] @@ -3500,7 +3657,8 @@ pub struct PluginsUninstallArgs { /// note: this updates the plugin itself, not the runtime versions #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise plugins update # update all plugins\n $ mise plugins update cmake # update only cmake\n $ mise plugins update cmake#beta # specify a ref" + after_long_help = "Examples:\n\n $ mise plugins update # update all plugins\n $ mise plugins update cmake # update only cmake\n $ mise plugins update cmake#beta # specify a ref", + effect = "write" )] pub struct PluginsUpdateArgs { #[usage( @@ -3517,6 +3675,7 @@ pub struct PluginsUpdateArgs { /// Manage plugins #[derive(Args)] +#[usage(effect = "read")] pub struct PluginsArgs { /// list all available remote plugins /// @@ -3583,6 +3742,7 @@ pub enum PluginsCommands { /// Adds one or more packages to the project using the appropriate package manager. /// Package specs use the format `ecosystem:package`, e.g., `npm:react` or `npm:@types/react@19`. #[derive(Args)] +#[usage(effect = "write")] pub struct DepsAddArgs { /// Add as a development dependency #[usage(long = "dev", short = 'D')] @@ -3597,6 +3757,7 @@ pub struct DepsAddArgs { /// Checks if dependency lockfiles are newer than installed outputs /// and runs install commands if needed. #[derive(Args)] +#[usage(effect = "write")] pub struct DepsInstallArgs { /// Show why a provider is fresh or stale (requires a provider argument) #[usage(long = "explain")] @@ -3632,6 +3793,7 @@ pub struct DepsInstallArgs { /// Removes one or more packages from the project using the appropriate package manager. /// Package specs use the format `ecosystem:package`, e.g., `npm:lodash`. #[derive(Args)] +#[usage(effect = "destructive")] pub struct DepsRemoveArgs { /// Package(s) to remove (e.g., npm:lodash) #[usage(arg, name = "PACKAGES", required)] @@ -3649,7 +3811,8 @@ pub struct DepsRemoveArgs { /// unless skipped with the --no-deps flag. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise deps # Install all project dependencies\n $ mise deps install # Same as bare `mise deps`\n $ mise deps install --force # Force reinstall even if fresh\n $ mise deps install --dry-run # Show what would run\n $ mise deps --monorepo # Install deps from explicit monorepo config roots\n $ mise deps add npm:react # Add a dependency\n $ mise deps add -D npm:vitest # Add a dev dependency\n $ mise deps remove npm:lodash # Remove a dependency\n\nConfiguration:\n\n```toml\n# Built-in npm provider (auto-detects lockfile)\n[deps.npm]\nauto = true # Auto-run before mise x/run\n\n# Custom provider\n[deps.codegen]\nauto = true\nsources = [\"schema/*.graphql\"]\noutputs = [\"src/generated/\"]\nrun = \"npm run codegen\"\n\n[deps]\ndisable = [\"npm\"] # Disable specific providers at runtime\n```" + after_long_help = "Examples:\n\n $ mise deps # Install all project dependencies\n $ mise deps install # Same as bare `mise deps`\n $ mise deps install --force # Force reinstall even if fresh\n $ mise deps install --dry-run # Show what would run\n $ mise deps --monorepo # Install deps from explicit monorepo config roots\n $ mise deps add npm:react # Add a dependency\n $ mise deps add -D npm:vitest # Add a dev dependency\n $ mise deps remove npm:lodash # Remove a dependency\n\nConfiguration:\n\n```toml\n# Built-in npm provider (auto-detects lockfile)\n[deps.npm]\nauto = true # Auto-run before mise x/run\n\n# Custom provider\n[deps.codegen]\nauto = true\nsources = [\"schema/*.graphql\"]\noutputs = [\"src/generated/\"]\nrun = \"npm run codegen\"\n\n[deps]\ndisable = [\"npm\"] # Disable specific providers at runtime\n```", + effect = "write" )] pub struct DepsArgs { /// Show why a provider is fresh or stale (requires a provider argument) @@ -3709,7 +3872,8 @@ pub enum DepsCommands { /// You can list prunable tools with `mise ls --prunable` #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise prune --dry-run\n rm -rf ~/.local/share/mise/versions/node/20.0.0\n rm -rf ~/.local/share/mise/versions/node/20.0.1" + after_long_help = "Examples:\n\n $ mise prune --dry-run\n rm -rf ~/.local/share/mise/versions/node/20.0.0\n rm -rf ~/.local/share/mise/versions/node/20.0.1", + effect = "destructive" )] pub struct PruneArgs { /// Do not actually delete anything @@ -3741,7 +3905,8 @@ pub struct PruneArgs { /// For example, `poetry` is shorthand for `asdf:mise-plugins/mise-poetry`. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise registry\n node core:node\n poetry asdf:mise-plugins/mise-poetry\n ubi cargo:ubi-cli\n\n $ mise registry poetry\n asdf:mise-plugins/mise-poetry" + after_long_help = "Examples:\n\n $ mise registry\n node core:node\n poetry asdf:mise-plugins/mise-poetry\n ubi cargo:ubi-cli\n\n $ mise registry poetry\n asdf:mise-plugins/mise-poetry", + effect = "read" )] pub struct RegistryArgs { /// Show only tools for this backend @@ -3769,6 +3934,7 @@ pub struct RegistryArgs { /// internal command to generate markdown from help #[derive(Args)] +#[usage(effect = "write")] pub struct RenderHelpArgs {} /// Creates new shims based on bin paths from currently installed tools. @@ -3791,7 +3957,8 @@ pub struct RenderHelpArgs {} /// currently active in mise.toml. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise reshim\n $ ~/.local/share/mise/shims/node -v\n v20.0.0" + after_long_help = "Examples:\n\n $ mise reshim\n $ ~/.local/share/mise/shims/node -v\n v20.0.0", + effect = "write" )] pub struct ReshimArgs { /// Removes all shims before reshimming @@ -4006,7 +4173,8 @@ pub struct RunArgs { /// non-fuzzy matches, use the `--match-type` flag. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise search jq\n Tool Description\n jq Command-line JSON processor. https://github.com/jqlang/jq\n jqp A TUI playground to experiment with jq. https://github.com/noahgorstein/jqp\n jiq jid on jq - interactive JSON query tool using jq expressions. https://github.com/fiatjaf/jiq\n gojq Pure Go implementation of jq. https://github.com/itchyny/gojq\n\n $ mise search --interactive\n Tool\n Search a tool\n ❯ jq Command-line JSON processor. https://github.com/jqlang/jq\n jqp A TUI playground to experiment with jq. https://github.com/noahgorstein/jqp\n jiq jid on jq - interactive JSON query tool using jq expressions. https://github.com/fiatjaf/jiq\n gojq Pure Go implementation of jq. https://github.com/itchyny/gojq\n /jq \n esc clear filter • enter confirm" + after_long_help = "Examples:\n\n $ mise search jq\n Tool Description\n jq Command-line JSON processor. https://github.com/jqlang/jq\n jqp A TUI playground to experiment with jq. https://github.com/noahgorstein/jqp\n jiq jid on jq - interactive JSON query tool using jq expressions. https://github.com/fiatjaf/jiq\n gojq Pure Go implementation of jq. https://github.com/itchyny/gojq\n\n $ mise search --interactive\n Tool\n Search a tool\n ❯ jq Command-line JSON processor. https://github.com/jqlang/jq\n jqp A TUI playground to experiment with jq. https://github.com/noahgorstein/jqp\n jiq jid on jq - interactive JSON query tool using jq expressions. https://github.com/fiatjaf/jiq\n gojq Pure Go implementation of jq. https://github.com/itchyny/gojq\n /jq \n esc clear filter • enter confirm", + effect = "read" )] pub struct SearchArgs { /// Show interactive search @@ -4039,6 +4207,7 @@ pub struct SearchArgs { /// package manager instead. See /// https://mise.jdx.dev/contributing.html#packaging-and-self-update-instructions #[derive(Args)] +#[usage(effect = "write")] pub struct SelfUpdateArgs { /// Update even if already up to date #[usage(long = "force", short = 'f')] @@ -4064,7 +4233,8 @@ pub struct SelfUpdateArgs { /// Use `-E ` to create/modify environment-specific config files like `mise..toml`. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise set NODE_ENV=production\n\n $ mise set NODE_ENV\n production\n\n $ mise set -E staging NODE_ENV=staging\n # creates or modifies mise.staging.toml\n\n $ mise set\n key value source\n NODE_ENV production ~/.config/mise/config.toml\n\n $ mise set --prompt PASSWORD\n Enter value for PASSWORD: [hidden input]\n\n Multiline Values (--stdin):\n\n $ cat private.key | mise set --stdin MY_KEY\n\n $ printf \"line1\\nline2\" | mise set --stdin MY_KEY\n\n [experimental] Age Encryption:\n\n $ mise set --age-encrypt API_KEY=secret\n\n $ mise set --age-encrypt --prompt API_KEY\n Enter value for API_KEY: [hidden input]" + after_long_help = "Examples:\n\n $ mise set NODE_ENV=production\n\n $ mise set NODE_ENV\n production\n\n $ mise set -E staging NODE_ENV=staging\n # creates or modifies mise.staging.toml\n\n $ mise set\n key value source\n NODE_ENV production ~/.config/mise/config.toml\n\n $ mise set --prompt PASSWORD\n Enter value for PASSWORD: [hidden input]\n\n Multiline Values (--stdin):\n\n $ cat private.key | mise set --stdin MY_KEY\n\n $ printf \"line1\\nline2\" | mise set --stdin MY_KEY\n\n [experimental] Age Encryption:\n\n $ mise set --age-encrypt API_KEY=secret\n\n $ mise set --age-encrypt --prompt API_KEY\n Enter value for API_KEY: [hidden input]", + effect = "write" )] pub struct SetArgs { /// Create/modify an environment-specific config file like .mise..toml @@ -4137,7 +4307,10 @@ pub struct SetArgs { /// Used with an array setting, this will append the value to the array. /// This modifies the contents of ~/.config/mise/config.toml #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise settings add disable_hints python_multi")] +#[usage( + after_long_help = "Examples:\n\n $ mise settings add disable_hints python_multi", + effect = "write" +)] pub struct SettingsAddArgs { /// Use the local config file instead of the global one #[usage(long = "local", short = 'l')] @@ -4157,7 +4330,10 @@ pub struct SettingsAddArgs { /// Note that aliases are also stored in this file /// but managed separately with `mise tool-alias get` #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise settings get idiomatic_version_file\n true")] +#[usage( + after_long_help = "Examples:\n\n $ mise settings get idiomatic_version_file\n true", + effect = "read" +)] pub struct SettingsGetArgs { /// Use the local config file instead of the global one #[usage(long = "local", short = 'l')] @@ -4175,7 +4351,8 @@ pub struct SettingsGetArgs { /// but managed separately with `mise tool-alias` #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise settings ls\n idiomatic_version_file = false\n ...\n\n $ mise settings ls python\n default_packages_file = \"~/.default-python-packages\"\n ..." + after_long_help = "Examples:\n\n $ mise settings ls\n idiomatic_version_file = false\n ...\n\n $ mise settings ls python\n default_packages_file = \"~/.default-python-packages\"\n ...", + effect = "read" )] pub struct SettingsLsArgs { /// List all settings @@ -4207,7 +4384,10 @@ pub struct SettingsLsArgs { /// With `--local`, modifies the local config file instead. /// See https://mise.jdx.dev/configuration.html#target-file-for-write-operations #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise settings idiomatic_version_file=true")] +#[usage( + after_long_help = "Examples:\n\n $ mise settings idiomatic_version_file=true", + effect = "write" +)] pub struct SettingsSetArgs { /// Use the local config file instead of the global one #[usage(long = "local", short = 'l')] @@ -4224,7 +4404,10 @@ pub struct SettingsSetArgs { /// /// This modifies the contents of ~/.config/mise/config.toml #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise settings unset idiomatic_version_file")] +#[usage( + after_long_help = "Examples:\n\n $ mise settings unset idiomatic_version_file", + effect = "write" +)] pub struct SettingsUnsetArgs { /// Use the local config file instead of the global one #[usage(long = "local", short = 'l')] @@ -4236,7 +4419,8 @@ pub struct SettingsUnsetArgs { #[derive(Args)] #[usage( - after_long_help = "Examples:\n # list all settings\n $ mise settings\n\n # get the value of the setting \"always_keep_download\"\n $ mise settings always_keep_download\n\n # set the value of the setting \"always_keep_download\" to \"true\"\n $ mise settings always_keep_download=true\n\n # set the value of the setting \"node.mirror_url\" to \"https://npmmirror.com/mirrors/node/\"\n $ mise settings node.mirror_url https://npmmirror.com/mirrors/node/" + after_long_help = "Examples:\n # list all settings\n $ mise settings\n\n # get the value of the setting \"always_keep_download\"\n $ mise settings always_keep_download\n\n # set the value of the setting \"always_keep_download\" to \"true\"\n $ mise settings always_keep_download=true\n\n # set the value of the setting \"node.mirror_url\" to \"https://npmmirror.com/mirrors/node/\"\n $ mise settings node.mirror_url https://npmmirror.com/mirrors/node/", + effect = "write" )] pub struct SettingsArgs { /// List all settings @@ -4293,7 +4477,10 @@ pub enum SettingsCommands { /// This works by setting environment variables for the current shell session /// such as `MISE_NODE_VERSION=20` which is "eval"ed as a shell function created by `mise activate`. #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise shell node@20\n $ node -v\n v20.0.0")] +#[usage( + after_long_help = "Examples:\n\n $ mise shell node@20\n $ node -v\n v20.0.0", + effect = "read" +)] pub struct ShellArgs { #[usage( help = "Number of jobs to run in parallel\n[default: 4]", @@ -4315,7 +4502,10 @@ pub struct ShellArgs { /// Show the command for a shell alias #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise shell-alias get ll\n ls -la")] +#[usage( + after_long_help = "Examples:\n\n $ mise shell-alias get ll\n ls -la", + effect = "read" +)] pub struct ShellAliasGetArgs { /// The alias to show #[usage(arg, name = "shell_alias")] @@ -4328,7 +4518,8 @@ pub struct ShellAliasGetArgs { /// These are defined in `mise.toml` under the `[shell_alias]` section. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise shell-alias ls\n alias command\n ll ls -la\n gs git status" + after_long_help = "Examples:\n\n $ mise shell-alias ls\n alias command\n ll ls -la\n gs git status", + effect = "read" )] pub struct ShellAliasLsArgs { /// Don't show table header @@ -4341,7 +4532,8 @@ pub struct ShellAliasLsArgs { /// This modifies the contents of ~/.config/mise/config.toml #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise shell-alias set ll \"ls -la\"\n $ mise shell-alias set gs \"git status\"" + after_long_help = "Examples:\n\n $ mise shell-alias set ll \"ls -la\"\n $ mise shell-alias set gs \"git status\"", + effect = "write" )] pub struct ShellAliasSetArgs { /// The alias name @@ -4356,7 +4548,10 @@ pub struct ShellAliasSetArgs { /// /// This modifies the contents of ~/.config/mise/config.toml #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise shell-alias unset ll")] +#[usage( + after_long_help = "Examples:\n\n $ mise shell-alias unset ll", + effect = "write" +)] pub struct ShellAliasUnsetArgs { /// The alias to remove #[usage(arg, name = "shell_alias")] @@ -4365,6 +4560,7 @@ pub struct ShellAliasUnsetArgs { /// Manage shell aliases. #[derive(Args)] +#[usage(effect = "read")] pub struct ShellAliasArgs { /// Don't show table header #[usage(long = "no-header")] @@ -4391,6 +4587,7 @@ pub enum ShellAliasCommands { /// Show the companies sponsoring mise and the jdx.dev open source tools #[derive(Args)] +#[usage(effect = "read")] pub struct SponsorsArgs {} /// Symlinks all tool versions from an external tool into mise @@ -4400,7 +4597,8 @@ pub struct SponsorsArgs {} /// This won't overwrite any existing installs but will overwrite any existing symlinks #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ brew install node@18 node@20\n $ mise sync node --brew\n $ mise use -g node@18 - uses Homebrew-provided node" + after_long_help = "Examples:\n\n $ brew install node@18 node@20\n $ mise sync node --brew\n $ mise use -g node@18 - uses Homebrew-provided node", + effect = "write" )] pub struct SyncNodeArgs { /// Get tool versions from Homebrew @@ -4421,7 +4619,8 @@ pub struct SyncNodeArgs { /// This won't overwrite any existing installs but will overwrite any existing symlinks #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ pyenv install 3.11.0\n $ mise sync python --pyenv\n $ mise use -g python@3.11.0 - uses pyenv-provided python\n\n $ uv python install 3.11.0\n $ mise install python@3.10.0\n $ mise sync python --uv\n $ mise x python@3.11.0 -- python -V - uses uv-provided python\n $ uv run -p 3.10.0 -- python -V - uses mise-provided python" + after_long_help = "Examples:\n\n $ pyenv install 3.11.0\n $ mise sync python --pyenv\n $ mise use -g python@3.11.0 - uses pyenv-provided python\n\n $ uv python install 3.11.0\n $ mise install python@3.10.0\n $ mise sync python --uv\n $ mise x python@3.11.0 -- python -V - uses uv-provided python\n $ uv run -p 3.10.0 -- python -V - uses mise-provided python", + effect = "write" )] pub struct SyncPythonArgs { /// Get tool versions from pyenv @@ -4435,7 +4634,8 @@ pub struct SyncPythonArgs { /// Symlinks all ruby tool versions from an external tool into mise #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ brew install ruby\n $ mise sync ruby --brew\n $ mise use -g ruby - Use the latest version of Ruby installed by Homebrew" + after_long_help = "Examples:\n\n $ brew install ruby\n $ mise sync ruby --brew\n $ mise use -g ruby - Use the latest version of Ruby installed by Homebrew", + effect = "write" )] pub struct SyncRubyArgs { /// Get tool versions from Homebrew @@ -4445,6 +4645,7 @@ pub struct SyncRubyArgs { /// Synchronize tools from other version managers with mise #[derive(Args)] +#[usage(effect = "read")] pub struct SyncArgs { #[usage(subcommand)] pub command: SyncCommands, @@ -4469,7 +4670,8 @@ pub enum SyncCommands { /// See https://mise.jdx.dev/configuration.html#target-file-for-write-operations #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise tasks add pre-commit --depends \"test\" --depends \"render\" -- echo pre-commit" + after_long_help = "Examples:\n\n $ mise tasks add pre-commit --depends \"test\" --depends \"render\" -- echo pre-commit", + effect = "write" )] pub struct TasksAddArgs { /// Other names for the task @@ -4527,7 +4729,8 @@ pub struct TasksAddArgs { /// Display a tree visualization of a dependency graph #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # Show dependencies for all tasks\n $ mise tasks deps\n\n # Show dependencies for the \"lint\", \"test\" and \"check\" tasks\n $ mise tasks deps lint test check\n\n # Show dependencies in DOT format\n $ mise tasks deps --dot\n\n # Collapse repeated dependencies\n $ mise tasks deps --compact" + after_long_help = "Examples:\n\n # Show dependencies for all tasks\n $ mise tasks deps\n\n # Show dependencies for the \"lint\", \"test\" and \"check\" tasks\n $ mise tasks deps lint test check\n\n # Show dependencies in DOT format\n $ mise tasks deps --dot\n\n # Collapse repeated dependencies\n $ mise tasks deps --compact", + effect = "read" )] pub struct TasksDepsArgs { /// Collapse repeated dependencies after their first occurrence @@ -4551,7 +4754,10 @@ pub struct TasksDepsArgs { /// /// The task will be created as a standalone script if it does not already exist. #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise tasks edit build\n $ mise tasks edit test")] +#[usage( + after_long_help = "Examples:\n\n $ mise tasks edit build\n $ mise tasks edit test", + effect = "write" +)] pub struct TasksEditArgs { /// Display the path to the task instead of editing it #[usage(long = "path", short = 'p')] @@ -4564,7 +4770,8 @@ pub struct TasksEditArgs { /// [experimental] Inspect the workspace project graph #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # Inspect projects and their dependency edges\n $ mise tasks graph\n\n # Emit the project graph as JSON\n $ mise tasks graph --json\n\n # Explain where inferred projects and task fields came from\n $ mise tasks graph --explain" + after_long_help = "Examples:\n\n # Inspect projects and their dependency edges\n $ mise tasks graph\n\n # Emit the project graph as JSON\n $ mise tasks graph --json\n\n # Explain where inferred projects and task fields came from\n $ mise tasks graph --explain", + effect = "read" )] pub struct TasksGraphArgs { /// Output the project graph as JSON @@ -4581,7 +4788,8 @@ pub struct TasksGraphArgs { /// Get information about a task #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise tasks info\n Name: test\n Aliases: t\n Description: Test the application\n Source: ~/src/myproj/mise.toml\n\n $ mise tasks info test --json\n {\n \"name\": \"test\",\n \"aliases\": \"t\",\n \"description\": \"Test the application\",\n \"source\": \"~/src/myproj/mise.toml\",\n \"config_sources\": [\"~/src/myproj/mise.toml\"],\n \"depends\": [],\n \"env\": {},\n \"dir\": null,\n \"hide\": false,\n \"raw\": false,\n \"sources\": [],\n \"outputs\": [],\n \"run\": [\n \"echo \\\"testing!\\\"\"\n ],\n \"file\": null,\n \"usage_spec\": {}\n }" + after_long_help = "Examples:\n\n $ mise tasks info\n Name: test\n Aliases: t\n Description: Test the application\n Source: ~/src/myproj/mise.toml\n\n $ mise tasks info test --json\n {\n \"name\": \"test\",\n \"aliases\": \"t\",\n \"description\": \"Test the application\",\n \"source\": \"~/src/myproj/mise.toml\",\n \"config_sources\": [\"~/src/myproj/mise.toml\"],\n \"depends\": [],\n \"env\": {},\n \"dir\": null,\n \"hide\": false,\n \"raw\": false,\n \"sources\": [],\n \"outputs\": [],\n \"run\": [\n \"echo \\\"testing!\\\"\"\n ],\n \"file\": null,\n \"usage_spec\": {}\n }", + effect = "read" )] pub struct TasksInfoArgs { /// Output in JSON format @@ -4593,7 +4801,7 @@ pub struct TasksInfoArgs { } #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise tasks ls")] +#[usage(after_long_help = "Examples:\n\n $ mise tasks ls", effect = "read")] pub struct TasksLsArgs { /// Only show global tasks #[usage(long = "global", short = 'g')] @@ -4849,7 +5057,8 @@ pub struct TasksRunArgs { /// Validate tasks for common errors and issues #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # Validate all tasks\n $ mise tasks validate\n\n # Validate specific tasks\n $ mise tasks validate build test\n\n # Output results as JSON\n $ mise tasks validate --json\n\n # Only show errors (skip warnings)\n $ mise tasks validate --errors-only\n\nValidation Checks:\n\nThe validate command performs the following checks:\n\n • Circular Dependencies: Detects dependency cycles\n • Missing References: Finds references to nonexistent tasks\n • Usage Spec Parsing: Validates #USAGE directives and specs\n • Timeout Format: Checks timeout values are valid durations\n • Alias Conflicts: Detects duplicate aliases across tasks\n • File Existence: Verifies file-based tasks exist\n • Directory Templates: Validates directory paths and templates\n • Shell Commands: Checks shell executables exist\n • Glob Patterns: Validates source and output patterns\n • Run Entries: Ensures tasks reference valid dependencies" + after_long_help = "Examples:\n\n # Validate all tasks\n $ mise tasks validate\n\n # Validate specific tasks\n $ mise tasks validate build test\n\n # Output results as JSON\n $ mise tasks validate --json\n\n # Only show errors (skip warnings)\n $ mise tasks validate --errors-only\n\nValidation Checks:\n\nThe validate command performs the following checks:\n\n • Circular Dependencies: Detects dependency cycles\n • Missing References: Finds references to nonexistent tasks\n • Usage Spec Parsing: Validates #USAGE directives and specs\n • Timeout Format: Checks timeout values are valid durations\n • Alias Conflicts: Detects duplicate aliases across tasks\n • File Existence: Verifies file-based tasks exist\n • Directory Templates: Validates directory paths and templates\n • Shell Commands: Checks shell executables exist\n • Glob Patterns: Validates source and output patterns\n • Run Entries: Ensures tasks reference valid dependencies", + effect = "read" )] pub struct TasksValidateArgs { /// Only show errors (skip warnings) @@ -4868,7 +5077,7 @@ pub struct TasksValidateArgs { /// Manage tasks #[derive(Args)] -#[usage(after_long_help = "Examples:\n\n $ mise tasks ls")] +#[usage(after_long_help = "Examples:\n\n $ mise tasks ls", effect = "read")] pub struct TasksArgs { /// Only show global tasks #[usage(long = "global", short = 'g')] @@ -4980,7 +5189,8 @@ pub struct TestToolArgs { /// Forgejo token #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise token forgejo\n codeberg.org: a180…61f6 (source: FORGEJO_TOKEN)\n\n $ mise token forgejo --unmask\n codeberg.org: a18099ca69064be387fbe37b8ad1d333758361f6 (source: FORGEJO_TOKEN)\n\n $ mise token forgejo forgejo.mycompany.com\n forgejo.mycompany.com: (none)" + after_long_help = "Examples:\n\n $ mise token forgejo\n codeberg.org: a180…61f6 (source: FORGEJO_TOKEN)\n\n $ mise token forgejo --unmask\n codeberg.org: a18099ca69064be387fbe37b8ad1d333758361f6 (source: FORGEJO_TOKEN)\n\n $ mise token forgejo forgejo.mycompany.com\n forgejo.mycompany.com: (none)", + effect = "read" )] pub struct TokenForgejoArgs { /// Show the full unmasked token @@ -4994,7 +5204,8 @@ pub struct TokenForgejoArgs { /// GitHub token #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise token github\n github.com: ghp_…xxxx (source: GITHUB_TOKEN)\n\n $ mise token github --unmask\n github.com: ghp_xxxxxxxxxxxx (source: GITHUB_TOKEN)\n\n $ mise token github github.mycompany.com\n github.mycompany.com: (none)\n\n $ mise token github --oauth --refresh\n github.com: gho_…xxxx (source: GitHub OAuth)" + after_long_help = "Examples:\n\n $ mise token github\n github.com: ghp_…xxxx (source: GITHUB_TOKEN)\n\n $ mise token github --unmask\n github.com: ghp_xxxxxxxxxxxx (source: GITHUB_TOKEN)\n\n $ mise token github github.mycompany.com\n github.mycompany.com: (none)\n\n $ mise token github --oauth --refresh\n github.com: gho_…xxxx (source: GitHub OAuth)", + effect = "read" )] pub struct TokenGithubArgs { /// Resolve only via the native GitHub OAuth source (cache, refresh, or device-code flow), bypassing other token sources @@ -5017,7 +5228,8 @@ pub struct TokenGithubArgs { /// GitLab token #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise token gitlab\n gitlab.com: glpa…xxxx (source: GITLAB_TOKEN)\n\n $ mise token gitlab --unmask\n gitlab.com: glpat-xxxxxxxxxxxx (source: GITLAB_TOKEN)\n\n $ mise token gitlab gitlab.mycompany.com\n gitlab.mycompany.com: (none)" + after_long_help = "Examples:\n\n $ mise token gitlab\n gitlab.com: glpa…xxxx (source: GITLAB_TOKEN)\n\n $ mise token gitlab --unmask\n gitlab.com: glpat-xxxxxxxxxxxx (source: GITLAB_TOKEN)\n\n $ mise token gitlab gitlab.mycompany.com\n gitlab.mycompany.com: (none)", + effect = "read" )] pub struct TokenGitlabArgs { /// Show the full unmasked token @@ -5030,6 +5242,7 @@ pub struct TokenGitlabArgs { /// Display git provider tokens mise will use #[derive(Args)] +#[usage(effect = "read")] pub struct TokenArgs { #[usage(subcommand)] pub command: TokenCommands, @@ -5051,7 +5264,8 @@ pub enum TokenCommands { /// Gets information about a tool #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise tool node\n Backend: core\n Installed Versions: 20.0.0 22.0.0\n Active Version: 20.0.0\n Requested Version: 20\n Config Source: ~/.config/mise/mise.toml\n Tool Options: [none]" + after_long_help = "Examples:\n\n $ mise tool node\n Backend: core\n Installed Versions: 20.0.0 22.0.0\n Active Version: 20.0.0\n Requested Version: 20\n Config Source: ~/.config/mise/mise.toml\n Tool Options: [none]", + effect = "read" )] pub struct ToolArgs { /// Output in JSON format @@ -5131,7 +5345,8 @@ pub struct ToolStubArgs { /// worktrees can check out branches with different config contents. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # trusts ~/some_dir/mise.toml\n $ mise trust ~/some_dir/mise.toml\n\n # trusts mise.toml in the current or parent directory\n $ mise trust" + after_long_help = "Examples:\n\n # trusts ~/some_dir/mise.toml\n $ mise trust ~/some_dir/mise.toml\n\n # trusts mise.toml in the current or parent directory\n $ mise trust", + effect = "write" )] pub struct TrustArgs { /// Trust all config files in the current directory, its parents, and its subdirectories @@ -5161,7 +5376,8 @@ pub struct TrustArgs { /// This only removes the installed version, it does not modify mise.toml. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # will uninstall specific version\n $ mise uninstall node@18.0.0\n\n # will uninstall the current node version (if only one version is installed)\n $ mise uninstall node\n\n # will uninstall all installed versions of node\n $ mise uninstall --all node@18.0.0 # will uninstall all node versions" + after_long_help = "Examples:\n\n # will uninstall specific version\n $ mise uninstall node@18.0.0\n\n # will uninstall the current node version (if only one version is installed)\n $ mise uninstall node\n\n # will uninstall all installed versions of node\n $ mise uninstall --all node@18.0.0 # will uninstall all node versions", + effect = "destructive" )] pub struct UninstallArgs { /// Delete all installed versions @@ -5185,7 +5401,8 @@ pub struct UninstallArgs { /// By default, this command modifies `mise.toml` in the current directory. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # Remove NODE_ENV from the current directory's config\n $ mise unset NODE_ENV\n\n # Remove NODE_ENV from the global config\n $ mise unset NODE_ENV -g" + after_long_help = "Examples:\n\n # Remove NODE_ENV from the current directory's config\n $ mise unset NODE_ENV\n\n # Remove NODE_ENV from the global config\n $ mise unset NODE_ENV -g", + effect = "write" )] pub struct UnsetArgs { /// Specify a file to use instead of `mise.toml` @@ -5208,6 +5425,7 @@ pub struct UnsetArgs { /// No longer trust a config, will prompt in the future #[derive(Args)] +#[usage(effect = "write")] pub struct UntrustArgs { /// The config file to untrust #[usage(arg, name = "CONFIG_FILE")] @@ -5234,7 +5452,8 @@ pub struct UntrustArgs { /// Will also prune the installed version if no other configurations are using it. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # will uninstall specific version\n $ mise unuse node@18.0.0\n\n # will uninstall specific version from global config\n $ mise unuse -g node@18.0.0\n\n # will uninstall specific version from .mise.local.toml\n $ mise unuse --env local node@20\n\n # will uninstall specific version from .mise.staging.toml\n $ mise unuse --env staging node@20" + after_long_help = "Examples:\n\n # will uninstall specific version\n $ mise unuse node@18.0.0\n\n # will uninstall specific version from global config\n $ mise unuse -g node@18.0.0\n\n # will uninstall specific version from .mise.local.toml\n $ mise unuse --env local node@20\n\n # will uninstall specific version from .mise.staging.toml\n $ mise unuse --env staging node@20", + effect = "destructive" )] pub struct UnuseArgs { /// Create/modify an environment-specific config file like .mise..toml @@ -5265,7 +5484,8 @@ pub struct UnuseArgs { /// This will update mise.lock if it is enabled, see https://mise.jdx.dev/configuration/settings.html#lockfile #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # Upgrades node to the latest version matching the range in mise.toml\n $ mise upgrade node\n\n # Upgrades node to the latest version and bumps the version in mise.toml\n $ mise upgrade node --bump\n\n # Upgrades all tools to the latest versions\n $ mise upgrade\n\n # Upgrades all tools to the latest versions and bumps the version in mise.toml\n $ mise upgrade --bump\n\n # Just print what would be done, don't actually do it\n $ mise upgrade --dry-run\n\n # Upgrades node and python to the latest versions\n $ mise upgrade node python\n\n # Upgrade all tools except go\n $ mise upgrade --exclude go\n\n # Show a multiselect menu to choose which tools to upgrade\n $ mise upgrade --interactive\n\n # Only upgrade tools defined in local mise.toml, not global ones\n $ mise upgrade --local" + after_long_help = "Examples:\n\n # Upgrades node to the latest version matching the range in mise.toml\n $ mise upgrade node\n\n # Upgrades node to the latest version and bumps the version in mise.toml\n $ mise upgrade node --bump\n\n # Upgrades all tools to the latest versions\n $ mise upgrade\n\n # Upgrades all tools to the latest versions and bumps the version in mise.toml\n $ mise upgrade --bump\n\n # Just print what would be done, don't actually do it\n $ mise upgrade --dry-run\n\n # Upgrades node and python to the latest versions\n $ mise upgrade node python\n\n # Upgrade all tools except go\n $ mise upgrade --exclude go\n\n # Show a multiselect menu to choose which tools to upgrade\n $ mise upgrade --interactive\n\n # Only upgrade tools defined in local mise.toml, not global ones\n $ mise upgrade --local", + effect = "write" )] pub struct UpgradeArgs { /// Display multiselect menu to choose which tools to upgrade @@ -5346,6 +5566,7 @@ pub struct UpgradeArgs { /// /// See https://usage.jdx.dev for more information on this specification. #[derive(Args)] +#[usage(effect = "read")] pub struct UsageArgs {} /// Installs a tool and adds the version to mise.toml. @@ -5369,7 +5590,8 @@ pub struct UsageArgs {} /// Use the `--global` flag to use the global config file instead. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # run with no arguments to use the interactive selector\n $ mise use\n\n # set the current version of node to 20.x in mise.toml of current directory\n # will write the fuzzy version (e.g.: 20)\n $ mise use node@20\n\n # set the current version of node to 20.x in ~/.config/mise/config.toml\n # will write the precise version (e.g.: 20.0.0)\n $ mise use -g --pin node@20\n\n # sets .mise.local.toml (which is intended not to be committed to a project)\n $ mise use --env local node@20\n\n # sets .mise.staging.toml (which is used if MISE_ENV=staging)\n $ mise use --env staging node@20" + after_long_help = "Examples:\n\n # run with no arguments to use the interactive selector\n $ mise use\n\n # set the current version of node to 20.x in mise.toml of current directory\n # will write the fuzzy version (e.g.: 20)\n $ mise use node@20\n\n # set the current version of node to 20.x in ~/.config/mise/config.toml\n # will write the precise version (e.g.: 20.0.0)\n $ mise use -g --pin node@20\n\n # sets .mise.local.toml (which is intended not to be committed to a project)\n $ mise use --env local node@20\n\n # sets .mise.staging.toml (which is used if MISE_ENV=staging)\n $ mise use --env staging node@20", + effect = "write" )] pub struct UseArgs { /// Create/modify an environment-specific config file like .mise..toml @@ -5443,7 +5665,8 @@ pub struct UseArgs { /// If the version is out of date, it will display a warning. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise version\n $ mise --version\n $ mise -v\n $ mise -V" + after_long_help = "Examples:\n\n $ mise version\n $ mise --version\n $ mise -v\n $ mise -V", + effect = "read" )] pub struct VersionArgs { /// Print the version information in JSON format @@ -5986,7 +6209,8 @@ pub struct WatchArgs { /// The tool must be installed for this to work. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n # Show the latest installed version of node\n # If it is is not installed, errors\n $ mise where node@20\n /home/jdx/.local/share/mise/installs/node/20.0.0\n\n # Show the current, active install directory of node\n # Errors if node is not referenced in any .tool-version file\n $ mise where node\n /home/jdx/.local/share/mise/installs/node/20.0.0" + after_long_help = "Examples:\n\n # Show the latest installed version of node\n # If it is is not installed, errors\n $ mise where node@20\n /home/jdx/.local/share/mise/installs/node/20.0.0\n\n # Show the current, active install directory of node\n # Errors if node is not referenced in any .tool-version file\n $ mise where node\n /home/jdx/.local/share/mise/installs/node/20.0.0", + effect = "read" )] pub struct WhereArgs { #[usage( @@ -6009,7 +6233,8 @@ pub struct WhereArgs { /// Use this to figure out what version of a tool is currently active. #[derive(Args)] #[usage( - after_long_help = "Examples:\n\n $ mise which node\n /home/username/.local/share/mise/installs/node/20.0.0/bin/node\n\n $ mise which node --plugin\n node\n\n $ mise which node --version\n 20.0.0" + after_long_help = "Examples:\n\n $ mise which node\n /home/username/.local/share/mise/installs/node/20.0.0/bin/node\n\n $ mise which node --plugin\n node\n\n $ mise which node --version\n 20.0.0", + effect = "read" )] pub struct WhichArgs { #[usage( diff --git a/benches/shadows/pitchfork/src/lib.rs b/benches/shadows/pitchfork/src/lib.rs index 2c056c9b0..311d28a03 100644 --- a/benches/shadows/pitchfork/src/lib.rs +++ b/benches/shadows/pitchfork/src/lib.rs @@ -24,6 +24,7 @@ use usage_derive::{Args, Cli, Subcommands}; /// fish (~/.config/fish/config.fish): /// pitchfork activate fish | source #[derive(Args)] +#[usage(effect = "read")] pub struct ActivateArgs { /// Shell to activate (bash, zsh, fish) #[usage(arg, name = "SHELL")] @@ -32,6 +33,7 @@ pub struct ActivateArgs { /// Generate JSON documentation for the web API endpoints #[derive(Args)] +#[usage(effect = "read")] pub struct ApiSchemaArgs {} /// Enable boot start for pitchfork supervisor @@ -50,6 +52,7 @@ pub struct ApiSchemaArgs {} /// under a specific user's home directory, configure `settings.supervisor.user` /// in your pitchfork configuration. #[derive(Args)] +#[usage(effect = "write")] pub struct BootEnableArgs {} /// Disable boot start for pitchfork supervisor @@ -57,12 +60,14 @@ pub struct BootEnableArgs {} /// Removes the boot start registration. Pitchfork will no longer start /// automatically on system boot. #[derive(Args)] +#[usage(effect = "write")] pub struct BootDisableArgs {} /// Check boot start status /// /// Reports whether pitchfork is configured to start on system boot. #[derive(Args)] +#[usage(effect = "read")] pub struct BootStatusArgs {} /// Enable or disable boot start @@ -95,6 +100,7 @@ pub struct BootStatusArgs {} /// pitchfork boot disable Don't start pitchfork on boot /// pitchfork boot status Check boot start status #[derive(Args)] +#[usage(effect = "read")] pub struct BootArgs { #[usage(subcommand)] pub command: BootCommands, @@ -114,6 +120,7 @@ pub enum BootCommands { } #[derive(Args)] +#[usage(effect = "read")] pub struct CdArgs { #[usage(long = "shell-pid", value_name = "SHELL_PID")] pub shell_pid: ::std::string::String, @@ -131,6 +138,7 @@ pub struct CdArgs { /// pitchfork clean Remove all stopped/failed entries /// pitchfork c Alias for 'clean' #[derive(Args)] +#[usage(effect = "write")] pub struct CleanArgs {} /// Add a new daemon to pitchfork.toml @@ -161,6 +169,7 @@ pub struct CleanArgs {} /// pitchfork daemons add worker --run './worker' --cron-schedule '0 * * * *' --cron-immediate /// Add cron daemon that triggers immediately #[derive(Args)] +#[usage(effect = "write")] pub struct DaemonsAddArgs { /// Command to run (can also use positional args) #[usage(long = "run", value_name = "RUN")] @@ -253,6 +262,7 @@ pub struct DaemonsAddArgs { /// Remove a daemon from a pitchfork config file #[derive(Args)] +#[usage(effect = "destructive")] pub struct DaemonsRemoveArgs { /// Remove from pitchfork.local.toml instead of pitchfork.toml #[usage(long = "local")] @@ -270,6 +280,7 @@ pub struct DaemonsRemoveArgs { /// List configured daemons from all merged config files. #[derive(Args)] +#[usage(effect = "read")] pub struct DaemonsArgs { /// Output in JSON format #[usage(long = "json")] @@ -304,6 +315,7 @@ pub enum DaemonsCommands { /// fish: /// pitchfork completion fish > ~/.config/fish/completions/pitchfork.fish #[derive(Args)] +#[usage(effect = "read")] pub struct CompletionArgs { /// Shell to generate completions for (bash, zsh, fish) #[usage(arg, name = "SHELL")] @@ -321,6 +333,7 @@ pub struct CompletionArgs { /// pitchfork d api Alias for 'disable' /// pitchfork list Shows 'disabled' status in output #[derive(Args)] +#[usage(effect = "write")] pub struct DisableArgs { /// Name of the daemon to disable #[usage(arg, name = "ID")] @@ -336,6 +349,7 @@ pub struct DisableArgs { /// pitchfork enable api Enable a disabled daemon /// pitchfork e api Alias for 'enable' #[derive(Args)] +#[usage(effect = "write")] pub struct EnableArgs { /// Name of the daemon to enable #[usage(arg, name = "ID")] @@ -365,6 +379,7 @@ pub struct EnableArgs { /// worker available /// db errored exit code 127 #[derive(Args)] +#[usage(effect = "read")] pub struct ListArgs { /// Hide the table header row #[usage(long = "hide-header")] @@ -402,6 +417,7 @@ pub struct ListArgs { /// Exits when the pipe reaches end of file, which happens once the daemon and /// every descendant holding the write end have gone. #[derive(Args)] +#[usage(effect = "write")] pub struct LogSinkArgs { /// Qualified id of the daemon whose output this is #[usage(long = "daemon-id", value_name = "DAEMON_ID")] @@ -462,9 +478,10 @@ pub struct LogSinkArgs { /// pitchfork logs api --clear Delete logs for 'api' /// pitchfork logs --clear Delete logs for all daemons #[derive(Args)] +#[usage(effect = "read")] pub struct LogsArgs { /// Delete logs - #[usage(long = "clear", short = 'c')] + #[usage(long = "clear", short = 'c', effect = "destructive")] pub clear: bool, /// Show last N lines of logs /// @@ -579,6 +596,7 @@ pub struct McpArgs {} /// pitchfork proxy trust /// sudo pitchfork proxy trust # Linux only #[derive(Args)] +#[usage(effect = "write")] pub struct ProxyTrustArgs { /// Path to the certificate file to trust (defaults to pitchfork's auto-generated cert) #[usage(long = "cert", value_name = "CERT")] @@ -598,6 +616,7 @@ pub struct ProxyTrustArgs { /// pitchfork proxy untrust /// sudo pitchfork proxy untrust # Linux only #[derive(Args)] +#[usage(effect = "write")] pub struct ProxyUntrustArgs { /// Path to the certificate file (defaults to pitchfork's auto-generated cert) #[usage(long = "cert", value_name = "CERT")] @@ -609,6 +628,7 @@ pub struct ProxyUntrustArgs { /// Displays the proxy configuration and lists all slugs from the global config /// with their project directory, daemon name, and current status (running/stopped, port). #[derive(Args)] +#[usage(effect = "read")] pub struct ProxyStatusArgs { /// Output in JSON format #[usage(long = "json")] @@ -628,6 +648,7 @@ pub struct ProxyStatusArgs { /// pitchfork proxy add api --daemon server /// pitchfork proxy add api --dir /home/user/my-api --daemon server #[derive(Args)] +#[usage(effect = "write")] pub struct ProxyAddArgs { /// Project directory (defaults to current directory) #[usage(long = "dir", value_name = "DIR")] @@ -648,6 +669,7 @@ pub struct ProxyAddArgs { /// Example: /// pitchfork proxy remove api #[derive(Args)] +#[usage(effect = "destructive")] pub struct ProxyRemoveArgs { /// The slug name to remove #[usage(arg, name = "SLUG")] @@ -675,6 +697,7 @@ pub struct ProxyRemoveArgs { /// remove Remove a slug mapping from the global config /// status Show all registered slugs and their current state #[derive(Args)] +#[usage(effect = "read")] pub struct ProxyArgs { #[usage(subcommand)] pub command: ProxyCommands, @@ -700,6 +723,7 @@ pub enum ProxyCommands { } #[derive(Args)] +#[usage(effect = "write")] pub struct ProjectEnterArgs { /// Host process PID that owns the session. Required #[usage(long = "pid", value_name = "PID")] @@ -711,6 +735,7 @@ pub struct ProjectEnterArgs { /// Leave a project session and evaluate its directory for autostop #[derive(Args)] +#[usage(effect = "write")] pub struct ProjectLeaveArgs { /// Host process PID that owns the session #[usage(long = "pid", value_name = "PID")] @@ -721,6 +746,7 @@ pub struct ProjectLeaveArgs { } #[derive(Args)] +#[usage(effect = "read")] pub struct ProjectListArgs { /// Output in JSON format #[usage(long = "json")] @@ -729,6 +755,7 @@ pub struct ProjectListArgs { /// Project session management for IDE and workspace integrations. #[derive(Args)] +#[usage(effect = "read")] pub struct ProjectArgs { #[usage(subcommand)] pub command: ProjectCommands, @@ -867,10 +894,12 @@ pub struct RunArgs { /// Generate JSON Schema for pitchfork.toml configuration #[derive(Args)] +#[usage(effect = "read")] pub struct SchemaArgs {} /// List all available settings with types and defaults #[derive(Args)] +#[usage(effect = "read")] pub struct SettingsListArgs { /// Only show settings in a specific group (e.g., "general", "web", "supervisor") #[usage(long = "group", value_name = "GROUP")] @@ -882,6 +911,7 @@ pub struct SettingsListArgs { /// Get the current value of a setting #[derive(Args)] +#[usage(effect = "read")] pub struct SettingsGetArgs { /// Output in JSON format #[usage(long = "json")] @@ -893,6 +923,7 @@ pub struct SettingsGetArgs { /// Set a setting value in a config file #[derive(Args)] +#[usage(effect = "write")] pub struct SettingsSetArgs { /// Write to the user-level global config (~/.config/pitchfork/config.toml) #[usage(long = "global")] @@ -934,6 +965,7 @@ pub struct SettingsSetArgs { /// pitchfork settings set supervisor.stop_timeout 10s --local /// pitchfork settings set supervisor.stop_timeout 10s --project #[derive(Args)] +#[usage(effect = "read")] pub struct SettingsArgs { /// Output in JSON format #[usage(long = "json")] @@ -957,6 +989,7 @@ pub enum SettingsCommands { /// Show the companies sponsoring pitchfork and the jdx.dev open source tools #[derive(Args)] +#[usage(effect = "read")] pub struct SponsorsArgs {} /// Starts a daemon from a pitchfork.toml file @@ -1040,6 +1073,7 @@ pub struct StartArgs { /// PID: 12345 /// Status: running #[derive(Args)] +#[usage(effect = "read")] pub struct StatusArgs { /// Output in JSON format #[usage(long = "json")] @@ -1071,6 +1105,7 @@ pub struct StatusArgs { /// pitchfork stop -g Stop all global daemons in config.toml /// pitchfork kill api Same as 'stop' (alias) #[derive(Args)] +#[usage(effect = "write")] pub struct StopArgs { /// Stop all daemons in the named group #[usage(long = "group", value_name = "GROUP")] @@ -1119,6 +1154,7 @@ pub struct SupervisorStartArgs { /// Gets the status of the pitchfork daemon #[derive(Args)] +#[usage(effect = "read")] pub struct SupervisorStatusArgs { /// Output in JSON format #[usage(long = "json")] @@ -1127,10 +1163,12 @@ pub struct SupervisorStatusArgs { /// Stops the internal pitchfork daemon running in the background #[derive(Args)] +#[usage(effect = "write")] pub struct SupervisorStopArgs {} /// Start, stop, and check the status of the pitchfork supervisor daemon #[derive(Args)] +#[usage(effect = "read")] pub struct SupervisorArgs { #[usage(subcommand)] pub command: SupervisorCommands, @@ -1160,6 +1198,7 @@ pub struct TuiArgs {} /// /// https://usage.jdx.dev #[derive(Args)] +#[usage(effect = "read")] pub struct UsageArgs {} /// Wait for a daemon to stop, tailing the logs along the way @@ -1174,6 +1213,7 @@ pub struct UsageArgs {} /// pitchfork w api Alias for 'wait' /// pitchfork wait api && echo done Run command after daemon stops #[derive(Args)] +#[usage(effect = "read")] pub struct WaitArgs { /// The name of the daemon to wait for #[usage(arg, name = "ID")] diff --git a/xtask/src/shadow.rs b/xtask/src/shadow.rs index 1ab69ce71..1a22b3fb8 100644 --- a/xtask/src/shadow.rs +++ b/xtask/src/shadow.rs @@ -412,6 +412,11 @@ fn emit_command(out: &mut String, cmd: &SpecCommand, ty: &Type, is_root: bool, r cmd.mounts.first().map(|m| format!("mount = {:?}", m.run)), "a `mount` on a command", ), + ( + !is_root && cmd.effect.is_some(), + cmd.effect.map(|e| format!("effect = {:?}", e.as_str())), + "`effect` on a command", + ), ] { if !present { continue; @@ -421,6 +426,11 @@ fn emit_command(out: &mut String, cmd: &SpecCommand, ty: &Type, is_root: bool, r Dialect::Clap | Dialect::Argh | Dialect::Bpaf => run.skipped.note(what), } } + // The root cannot carry one: the spec writer and the derive both refuse it, so + // emitting it here would be a shadow that does not compile. + if is_root && cmd.effect.is_some() { + run.skipped.note("`effect` on the root command"); + } match (is_root, dialect) { (true, Dialect::Usage) => { out.push_str("#[derive(Cli)]\n"); @@ -854,6 +864,14 @@ fn usage_flag_opts( if flag.require_equals { opts.push("require_equals".into()); } + if let Some(effect) = flag.effect { + opts.push(format!("effect = {:?}", effect.as_str())); + } + // The derive puts `effect` on the flag field, not on a nested value argument, so a + // spec that classified the value rather than the flag has nowhere to land. + if flag.arg.as_ref().and_then(|a| a.effect).is_some() { + skipped.note("`effect` on a flag's value argument"); + } if !flag.required_if.is_empty() { opts.push(selector_list("required_if", &flag.required_if)); } @@ -981,6 +999,12 @@ fn clap_flag_opts( if flag.require_equals { opts.push("require_equals = true".into()); } + if flag.effect.is_some() { + skipped.note("`effect` on a flag"); + } + if flag.arg.as_ref().and_then(|a| a.effect).is_some() { + skipped.note("`effect` on a flag's value argument"); + } if flag.global { opts.push("global = true".into()); } @@ -1126,6 +1150,9 @@ fn arg_drops(arg: &SpecArg, skipped: &mut Skipped) { if arg.hide { skipped.note("`hide` on an argument"); } + if arg.effect.is_some() { + skipped.note("`effect` on an argument"); + } if arg.choices.is_some() { skipped.note("`choices` on an argument"); } @@ -1195,6 +1222,12 @@ fn argh_flag_opts(flag: &SpecFlag, long: Option<&str>, skipped: &mut Skipped) -> if !flag.conflicts.is_empty() || !flag.requires.is_empty() { skipped.note("a relationship between flags"); } + if flag.effect.is_some() { + skipped.note("`effect` on a flag"); + } + if flag.arg.as_ref().and_then(|a| a.effect).is_some() { + skipped.note("`effect` on a flag's value argument"); + } opts } @@ -1245,6 +1278,12 @@ fn bpaf_flag_opts(flag: &SpecFlag, long: Option<&str>, skipped: &mut Skipped) -> if !flag.conflicts.is_empty() || !flag.requires.is_empty() { skipped.note("a relationship between flags"); } + if flag.effect.is_some() { + skipped.note("`effect` on a flag"); + } + if flag.arg.as_ref().and_then(|a| a.effect).is_some() { + skipped.note("`effect` on a flag's value argument"); + } opts } @@ -1292,6 +1331,12 @@ fn usage_arg_opts(arg: &SpecArg, skipped: &mut Skipped) -> Vec { if arg.hide { opts.push("hide".into()); } + // The derive refuses `effect` on a positional: supplying a flag changes what + // happens; a positional is the thing being acted on. Counted rather than + // written, so a spec that classified one is not silently flattened. + if arg.effect.is_some() { + skipped.note("`effect` on an argument"); + } // An argument can be backed by an environment variable and grouped under a heading // just as a flag can, and both reach `ArgMeta` — leaving them out made the shadow's // grammar quietly differ from the spec's for any spec that used them. @@ -1351,6 +1396,9 @@ fn clap_arg_opts(arg: &SpecArg, skipped: &mut Skipped) -> Vec { if arg.hide { opts.push("hide = true".into()); } + if arg.effect.is_some() { + skipped.note("`effect` on an argument"); + } if let Some(choices) = &arg.choices { opts.push(format!( "value_parser = ::clap::builder::PossibleValuesParser::new([{}])", @@ -2034,9 +2082,9 @@ mod tests { ); } - /// The three command-level properties, which only one of the two dialects can say. + /// The command-level properties clap cannot hear. usage declares all four. const COMMAND_PROPERTIES: &str = "name \"ex\"\nbin \"ex\"\ndefault_subcommand \"go\"\n\ - cmd \"go\" restart_token=\":::\" {\n mount run=\"ex tasks --usage\"\n}\n"; + cmd \"go\" restart_token=\":::\" effect=\"read\" {\n mount run=\"ex tasks --usage\"\n}\n"; #[test] fn the_usage_dialect_carries_the_command_properties() { @@ -2044,12 +2092,14 @@ mod tests { assert!(out.contains(r#"default_subcommand = "go""#), "{out}"); assert!(out.contains(r#"restart_token = ":::""#), "{out}"); assert!(out.contains(r#"mount = "ex tasks --usage""#), "{out}"); + assert!(out.contains(r#"effect = "read""#), "{out}"); - // Carried means not lost: none of the three may appear in the report. + // Carried means not lost: none of the four may appear in the report. for what in [ "`default_subcommand` on a command", "a `restart_token` on a command", "a `mount` on a command", + "`effect` on a command", ] { assert!( !skipped.counts.contains_key(what), @@ -2060,7 +2110,7 @@ mod tests { #[test] fn the_clap_dialect_counts_them_as_dropped() { - // clap has no way to say any of the three. The shadow is a fairness fixture, so + // clap has no way to say any of the four. The shadow is a fairness fixture, so // what it cannot carry has to be named — a silent drop would make the clap side // look like a faithful translation of a spec it cannot represent. let (out, skipped) = rendered_as(COMMAND_PROPERTIES, Dialect::Clap); @@ -2068,11 +2118,31 @@ mod tests { "`default_subcommand` on a command", "a `restart_token` on a command", "a `mount` on a command", + "`effect` on a command", ] { assert_eq!(skipped.counts.get(what), Some(&1), "{what}"); } assert!(!out.contains("restart_token"), "{out}"); assert!(!out.contains("default_subcommand"), "{out}"); + assert!(!out.contains("effect"), "{out}"); + } + + #[test] + fn the_usage_dialect_carries_a_flag_effect() { + // communique's `--force` is `effect="destructive"`. Dropping it was invisible + // in help — help does not print an effect — and only showed up once markdown + // from the shadow's KDL was compared to the checked-in spec. + let spec = "name \"ex\"\nbin \"ex\"\nflag \"--force\" effect=\"destructive\"\n"; + let (out, skipped) = rendered_as(spec, Dialect::Usage); + assert!(out.contains(r#"effect = "destructive""#), "{out}"); + assert!( + !skipped.counts.contains_key("`effect` on a flag"), + "expressible, so it should not be counted as dropped" + ); + + let (clap, skipped) = rendered_as(spec, Dialect::Clap); + assert_eq!(skipped.counts.get("`effect` on a flag"), Some(&1)); + assert!(!clap.contains("effect"), "{clap}"); } #[test]