Unclear documentation for `--invoke` flag syntax and return value display

[koke1997]

Description

While working with Wasmtime's CLI, I discovered undocumented behavior differences between the two syntaxes for invoking WebAssembly functions:

• wasmtime add.wasm --invoke add 1 2 (space syntax) - executes the function but doesn't display its return value
• wasmtime --invoke=add add.wasm 1 2 (equals sign syntax) - executes the function AND displays its return value

Both commands show warnings that this functionality is experimental, but the CLI documentation doesn't explain this syntax difference or mention that return value display is only enabled with the equals sign variant.

Example

Using a simple WebAssembly module with an add function that returns the sum of two integers:

(module
  (func $add (param $lhs i32) (param $rhs i32) (result i32)
     (i32.add
       (local.get $lhs)
       (local.get $rhs)
     )
  )
  (export "add" (func $add))
)

Compiled with wat2wasm add.wat, then:

# This command shows no return value
$ wasmtime add.wasm --invoke add 1 2

# This command shows '3' as the return value
$ wasmtime --invoke=add add.wasm 1 2
warning: using `--invoke` with a function that takes arguments is experimental and may break in the future
warning: using `--invoke` with a function that returns values is experimental and may break in the future
3

Suggested Documentation Improvement

I suggest updating the CLI documentation at https://docs.wasmtime.dev/cli-options.html to explain:

1. The difference between space syntax (--invoke function) and equals sign syntax (--invoke=function)
2. That function return values are only displayed with the equals sign syntax
3. That this feature is experimental and may change in future versions

This would help new users understand the expected behavior and avoid confusion when trying to view function return values.

I noticed this while doing a course from Linux Foundation , since resource mentions the first way of executing command without equal sign - https://trainingportal.linuxfoundation.org/learn/course/webassembly-components-from-cloud-to-edge-lfd134/webassembly-from-scratch/exploring-webassembly?page=7

Additional Context

• Wasmtime version: 32.0.0 (the current version I'm using)
• OS: Linux Ubuntu (but should be consistent across platforms)

[alexcrichton]

Hello and thanks for the report! I think there's some confusion going on here, although I'm not sure how best to resolve it.

To start off though I can try to clarify. Your first example of wasmtime add.wasm --invoke add 1 2 is not passing --invoke to Wasmtime, which I think is leading to some confusion. That's passing --invoke to the wasm module itself as an argument on the CLI. The module itself then has no entrypoint so nothing ends up happening, meaning the argument is effectively ignored. This is probably a situation where we should print a warning or something like that about no entrypoint being found. Unsure!

Your second example of wasmtime --invoke=add add.wasm 1 2 is using Wasmtime's own --invoke argument. Note that the = here is not relevant, this equally works as wasmtime --invoke add add.wasm 1 2. Whether or not you use = is a stylistic/command-line choice on your part and is orthogonal to everything else here. That you used = here and didn't use = in the first example is probably just coincidence.

Now overall I agree that this is all confusing! The warning here about this being unstable is quite longstanding and doesn't have any trajectory for being removed. Additionally we don't have a great mechanism for warning about passing Wasmtime arguments to the guest by accident. There's various degrees to which we can solve these issues, but I alas don't think that there's a silver bullet here.

For some of your concrete suggestions:

The difference between space syntax (--invoke function) and equals sign syntax (--invoke=function)

I believe this is mostly a mistaken deduction on your part. The = here shouldn't matter, but the position of --invoke does matter. If you find the opposite though please let us know, that's a bug!

That function return values are only displayed with the equals sign syntax

Like above I think this is a mistaken deduction where the position of --invoke matters, but the = does not. Passing --invoke after the wasm means it's an argument for the wasm itself, not Wasmtime.

That this feature is experimental and may change in future versions

Agreed! I do think we should document this.

I noticed this while doing a course from Linux Foundation

I alas can't access the link you pasted there, but one thing which may be happening is that Wasmtime 13.0.0 and prior (or some version around there) supported --invoke after the wasm module but it now no longer does. If the tutorial was written on the scale of years ago it may have been using this syntax.

[alexcrichton]

(I've also submitted #10793 now to help clarify the documentation, but if you feel there are still improvements to be made please let us know!)

[koke1997]

Hi,
Thank you very much for this explanation. It makes now sense to me how the CLI is accepting the arguments.
I think personally that this feature of testing exported functions via CLI is big gamechanger as it allows us to take modular approach in development.
The PR also looks good. I paste here also an image from course so you can see why i did raise this ticket.

Thanks again for the swift response!

[alexcrichton]

Yes if possible can you report a bug to that documentation? That's incorrect and --invoke needs to be before add.wasm

[koke1997]

Yes, I already posted in forum and also raised a ticket for this for Linux Foundation. You might not have access to the JIRA ticket, so here is a screenshot.

https://jira.linuxfoundation.org/plugins/servlet/desk/portal/15/TCCS-141351

https://forum.linuxfoundation.org/discussion/868852/wasmtime-cli-not-displaying-function-return-values-by-default#latest - here is the thread.

[alexcrichton]

I'm going to closet his as being mostly handled in #10793, but thanks again @koke1997 for raising this and if you think there'se more we can do please let us know!