wasi-cli
wasi-cli copied to clipboard
Command-Line Interface (CLI) World for WASI
WASI CLI World
A proposed WebAssembly System Interface API.
Current Phase
wasi-cli is currently in Phase 3.
Champions
- Dan Gohman
Portability Criteria
WASI CLI must have host implementations which can pass the testsuite on at least Windows, macOS, and Linux.
WASI CLI must have at least two complete independent implementations.
Table of Contents
- Introduction
- Goals [or Motivating Use Cases, or Scenarios]
- Non-goals
-
API walk-through
- Use case 1
- Use case 2
-
Detailed design discussion
-
Should stdout be an
output-stream
? -
Should stderr be an
output-stream
? -
Should environment variables be arguments to
command
?
-
Should stdout be an
- Stakeholder Interest & Feedback
- References & acknowledgements
Introduction
Wasi-cli a World proposal for a Command-Line Interface (CLI) environment. It provides APIs commonly available in such environments, such as filesystems and sockets, and also provides command-line facilities such as command-line arguments, environment variables, and stdio.
Goals
Wasi-cli aims to be useful for:
-
Interactive command-line argument programs.
-
Servers that use filesystems, sockets, and related APIs and expect to be started with a CLI-style command-line.
-
Stream filters that read from standard input and write to standard output.
Non-goals
Wasi-cli is not aiming to significantly re-imagine the concept of command-line interface programs. While WASI as a whole is exploring ideas such as Typed Main, wasi-cli sticks to the traditional list-of-strings style command-line arguments.
API walk-through
The full API documentation can be found here.
TODO [Walk through of how someone would use this API.]
[Use case 1]
[Provide example code snippets and diagrams explaining how the API would be used to solve the given problem]
[Use case 2]
[etc.]
Detailed design discussion
Should stdout be an output-stream
?
For server use cases, standard output (stdout) is typically used as a log,
where it's typically not meaningfully blocking, async, or fallible. It's just
a place for the program to send messages to and forget about them. One option
would be to give such use cases a dedicated API, which would have a single
function to allow printing strings that doesn't return a result
, meaning it
never fails.
However, it'd only be a minor simplification in practice, and dedicated cloud or edge use cases should ideally migrate to more specialized worlds than the wasi-cli world anyway, as they can result in much greater simplifications, so this doesn't seem worthwhile.
Should stderr be an output-stream
?
This is similar to the question for stdout, but for standard error (stderr), it's a little more tempting to do something like this because stderr is used in this logging style by many kinds of applications.
However, it seems better overall to keep stderr consistent with stdout, and focus our desires for simplification toward other worlds, which can achieve even greater simplifications.
Should environment variables be arguments to command
?
Environment variables are useful in some non-cli use cases, so leaving them
as separate imports means they can be used from worlds that don't have a
command
entrypoint.
Stakeholder Interest & Feedback
TODO before entering Phase 3.
[This should include a list of implementers who have expressed interest in implementing the proposal]
References & acknowledgements
The concept of wasi-cli has been in development for over a year since the proposal is posted here, and many people have contributed ideas that have influenced. Many thanks for valuable feedback and advice in particular from:
- Luke Wagner
- Pat Hickey