--usage

usage exec ​

Run a script through any interpreter, with its parsed arguments as environment variables

For scripts in a language usage has no dedicated command for. A shebang of #!/usr/bin/env -S usage exec node parses the arguments against the USAGE comments at the top of the file, then runs node <script> <args> with each flag and argument exported as usage_<name>. When a file named .<script>.usage.kdl sits beside the script, the spec is read from it instead of from the comments.

A command with whitespace in it is split like a shell would, so interpreter arguments can come before the script: #!/usr/bin/env -S usage exec "deno run --allow-env=usage_*" runs deno run --allow-env=usage_* <script> <args>. A name that is an existing file, or is found on PATH, is never split.

-h and --help belong to the script once one is named, so they print its help page rather than this one. Asked with no script to describe, they print this page.

Arguments ​

  • <COMMAND> — The interpreter to run the script with, such as node or python3, or a quoted command with its own arguments, such as "deno run --allow-env"
  • <BIN> — The script to run
  • [ARGS]… — Arguments to pass to the script

Flags ​

  • -h — Print the script's help page instead of running it
  • --help — Print the script's help page instead of running it
MIT LicenseCopyright © 2026jdx.dev