Update CLI run documentation

docs/cli-options.md

@@ -44,25 +44,92 @@ as well as the text format for WebAssembly (`*.wat`):
 wasmtime foo.wat
 ```
 
-**Wasm Modules**
+#### Running WebAssembly CLI programs
 
-A Wasm **module** exports raw functions directly. The `run` command accepts an optional `--invoke` argument, which is the name of an exported raw function (of the module) to run:
+WebAssembly modules or components can behave like a CLI program which means
+they're intended to look like a normal OS executable with a `main` function and
+run once to completion. This is the default mode of running a wasm provided to
+Wasmtime.
+
+For core WebAssembly modules this means that the function exported as an empty
+string, or the `_start` export, is invoked. For WebAssembly components this
+means that the `wasi:cli/run` interface is executed.
+
+For both core modules and components, CLI arguments are passed via WASI. Core
+modules receive arguments via WASIp1 APIs and components receive arguments via
+WASIp2 or later APIs. Arguments, flags, etc., are passed to the WebAssembly file
+after the file itself. For example,
+
+```console
+wasmtime foo.wasm --bar baz
+```
+
+Will pass `["foo.wasm", "--bar", "baz"]` as the list of arguments to the module.
+Note that flags for Wasmtime must be passed before the WebAssembly file, not
+afterwards. For example,
+
+```console
+wasmtime foo.wasm --dir .
+```
+
+Will pass `--dir .` to the `foo.wasm` program, not Wasmtime. If you want to
+mount the current directory you instead need to invoke
+
+```console
+wasmtime --dir . foo.wasm
+```
+
+All Wasmtime options must come before the WebAssembly file provided. All
+arguments afterwards are passed to the WebAssembly file itself.
+
+#### Running Custom Module exports
+
+If you're not running a "command" but want to run a specific export of a
+WebAssembly core module you can use the `--invoke` argument:
 
 ```console
 wasmtime run --invoke initialize foo.wasm
 ```
 
-**Wasm Components**
+This will invoke the `initialize` export of the `foo.wasm` module.
 
-A Wasm **component** uses typed interfaces defined by [the component model](https://component-model.bytecodealliance.org/design/components.html). The `run` command also accepts the optional `--invoke` argument for calling an exported function of a **component**. However, the calling of an exported function of a component uses [WAVE](https://github.com/bytecodealliance/wasm-tools/tree/a56e8d3d2a0b754e0465c668f8e4b68bad97590f/crates/wasm-wave#readme)(a human-oriented text encoding of Wasm Component Model values). For example:
+When invoking a WebAssembly function arguments to the function itself are parsed
+from CLI arguments. For example an `i32` argument to a WebAssembly module is
+parsed as a CLI argument for the module:
+
+```console
+wasmtime run --invoke add add.wasm 1 2
+```
+
+Note though that this syntax is unstable at this time and may change in the
+future. If you'd like to rely on this please open an issue, otherwise we request
+that you please don't rely on the exact output here.
+
+#### Running Custom Component exports
+
+Like core modules Wasmtime supports invoking arbitrary component exports.
+Components can export typed interfaces defined by [the component
+model](https://component-model.bytecodealliance.org/design/components.html). The
+`--invoke` argument is supported to skip calling `wasi:cli/run` and invoke a
+specific typed export instead. Arguments are passed with
+[WAVE](https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wasm-wave#readme)
+,a human-oriented text encoding of Wasm Component Model values. For example:
 
 ```console
 wasmtime run --invoke 'initialize()' foo.wasm
 ```
 
-You will notice that (when using WAVE) the exported function's name and exported function's parentheses are both enclosed in one set of single quotes, i.e. `'initialize()'`. This treats the exported function as a single argument, prevents issues with shell interpretation and signifies function invocation (as apposed to the function name just being referenced). Using WAVE (when calling exported functions of Wasm components) helps to distinguish function calls from other kinds of string arguments. Below are some more examples:
+You will notice that (when using WAVE) the exported function's name and exported
+function's parentheses are both enclosed in one set of single quotes, i.e.
+`'initialize()'`. This treats the exported function as a single argument in a
+Unix shell and prevents issues with shell interpretation and signifies function
+invocation (as apposed to the function name just being referenced). Using WAVE
+(when calling exported functions of Wasm components) helps to distinguish
+function calls from other kinds of string arguments. Below are some more
+examples:
 
-If your function takes a string argument, you surround the string argument in double quotes:
+If your function takes a string argument, you surround the string argument in
+double quotes:
 
 ```console
 wasmtime run --invoke 'initialize("hello")' foo.wasm
@@ -75,7 +142,11 @@ wasmtime run --invoke 'initialize("Pi", 3.14)' foo.wasm
 wasmtime run --invoke 'add(1, 2)' foo.wasm
 ```
 
-**Please note:** If you enclose your whole function call using double quotes, your string argument will require its double quotes to be escaped (escaping quotes is more complicated and harder to read and therefore not ideal). For example:
+**Please note:** If you enclose your whole function call using double quotes,
+your string argument will require its double quotes to be escaped (escaping
+quotes is more complicated and harder to read and therefore not ideal). For
+example:
+
 ```bash
 wasmtime run - invoke "initialize(\"hello\")" foo.wasm
 ```