1 files changed, 74 insertions, 0 deletions
diff --git a/docs/examples/subprocess.md b/docs/examples/subprocess.md
new file mode 100644
index 000000000..80d0cc7da
--- /dev/null
+++ b/docs/examples/subprocess.md
@@ -0,0 +1,74 @@
+## Run subprocess
+
+[API Reference](https://doc.deno.land/https/github.com/denoland/deno/releases/latest/download/lib.deno.d.ts#Deno.run)
+
+Example:
+
+```ts
+// create subprocess
+const p = Deno.run({
+  cmd: ["echo", "hello"],
+});
+
+// await its completion
+await p.status();
+```
+
+Run it:
+
+```shell
+$ deno run --allow-run ./subprocess_simple.ts
+hello
+```
+
+Here a function is assigned to `window.onload`. This function is called after
+the main script is loaded. This is the same as
+[onload](https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload)
+of the browsers, and it can be used as the main entrypoint.
+
+By default when you use `Deno.run()` subprocess inherits `stdin`, `stdout` and
+`stderr` of parent process. If you want to communicate with started subprocess
+you can use `"piped"` option.
+
+```ts
+const fileNames = Deno.args;
+
+const p = Deno.run({
+  cmd: [
+    "deno",
+    "run",
+    "--allow-read",
+    "https://deno.land/std/examples/cat.ts",
+    ...fileNames,
+  ],
+  stdout: "piped",
+  stderr: "piped",
+});
+
+const { code } = await p.status();
+
+if (code === 0) {
+  const rawOutput = await p.output();
+  await Deno.stdout.write(rawOutput);
+} else {
+  const rawError = await p.stderrOutput();
+  const errorString = new TextDecoder().decode(rawError);
+  console.log(errorString);
+}
+
+Deno.exit(code);
+```
+
+When you run it:
+
+```shell
+$ deno run --allow-run ./subprocess.ts <somefile>
+[file content]
+
+$ deno run --allow-run ./subprocess.ts non_existent_file.md
+
+Uncaught NotFound: No such file or directory (os error 2)
+    at DenoError (deno/js/errors.ts:22:5)
+    at maybeError (deno/js/errors.ts:41:12)
+    at handleAsyncMsgFromRust (deno/js/dispatch.ts:27:17)
+```