usage

When a file change occurs while the current task is still running, you can control how mise watch reacts using the -o or --on-busy-update flag:

• do-nothing (default): Ignore new events until the current run finishes.
• queue: Run the command again once the current run finishes if any events occurred.
• restart: Terminate the running command and start a new one immediately.
• signal: Send a signal to the running process (requires --signal <SIGNAL>).

Related Flags:

• -r or --restart: Shorthand for --on-busy-update=restart.
• --stop-signal <SIGNAL>: The signal sent to stop the command during a restart (default is SIGTERM on Unix). Use KILL on Windows.
• --stop-timeout <TIMEOUT>: How long to wait for a graceful exit before force-killing (e.g., 10s).

# Restart the task immediately if a file changes while it's running
mise watch -r my-dev-server

# Send SIGINT to a running process instead of killing it
mise watch -o signal -s SIGINT my-app

When using mount to define dynamic commands, the mounted command is treated as a different program. This affects how flags are handled:

1. Scope Isolation: Once a user enters a mounted command, global flags declared above the mount are no longer offered in completions.
2. Precedence: If a mounted command declares a flag with the same name as a global flag, the mounted command's flag takes precedence. For example, if a global flag --env <ENV> exists, but a mounted task defines --env <name> with specific choices, the completion will show the task's choices.
3. Global Propagation: Global flags are still recognized if they are placed before the mounted command (e.g., mycli --env prod run task1). In this position, they propagate into the mount command.

```kdl
flag "-E --env <ENV>" global=#true
cmd "run" {
	mount run="mycli mount-usage-tasks"
}

// Emitted by the mount:
cmd "task1" {
  flag "--env <name>" {
    choices "dev" "stage" "prod"
  }
}

Behavior Summary:

• mycli run task1 --<tab> $\rightarrow$ Shows only task1 flags.
• mycli run task1 --env <tab> $\rightarrow$ Shows dev, stage, prod (task choices) instead of the global <ENV>.
• mycli --env prod run task1 $\rightarrow$ Global flag is correctly recognized and propagates.

If your CLI has dynamic subcommands (e.g., a run command that executes tasks with varying arguments), you can use the mount property to inject usage specifications at runtime.

To implement this:

1. Create a hidden command (e.g., mycli mount-usage-tasks) that, when executed, emits a KDL usage spec describing the dynamic tasks.
2. Define a mount on the parent command in your static spec, pointing to that hidden command.

When a user triggers completion (e.g., mycli run <tab><tab>), the system executes the mount command and merges its output into the run command's specification.

Execution Note: Mounts are executed via sh -c (falling back to cmd /c on Windows). If your mount points to a shebang script, a POSIX shell must be available on the PATH.

// Static usage spec
cmd "mount-usage-tasks" hide=#true
cmd "run" {
	mount run="mycli mount-usage-tasks"
}

// Example of what the mount command might emit:

cmd "task1" {
  arg "arg1" help="task1 arg1"
  flag "flag1" help="task1 flag1"
}
cmd "task2" {
  arg "arg1" help="task2 arg1"
  flag "flag1" help="task2 flag1"
}

Commands can declare an effect to describe their impact on the system. This allows consumers (like documentation generators, wrapper scripts, or AI agents) to understand the safety of a command.

Important Rules:

• No Inheritance: effect is not inherited by subcommands. Each command must declare its own effect.
• Unknown is Unsafe: A command with no effect should be treated as "unknown" (consumers should ask for permission).
• Raising Effects: A flag or argument can raise the effect of a command. The total effect of an invocation is the maximum of the command's effect and the effect of every flag/argument supplied (read < write < destructive).
• No Lowering: A flag or argument can only ever raise the effect, never lower it (e.g., --dry-run cannot lower a destructive command to read).

Example of declaring effects:

cmd "ls" effect="read" help="List installed tools"
cmd "use" effect="write" help="Install a tool and add it to the config"
cmd "uninstall" effect="destructive" help="Remove a tool"

// Effect via child node
cmd "uninstall" {
  effect "destructive"
}

// Raising effect via flag
cmd "logs" effect="read" help="Show daemon logs" {
  flag "--clear" effect="destructive" help="Delete stored logs"
  flag "--follow"
}

// Raising effect via argument
cmd "settings" effect="read" {
  arg "[setting]"
  arg "[value]" effect="write"   // `settings foo` reads, `settings foo=bar` writes
}