1 files changed, 117 insertions, 0 deletions
diff --git a/docs/shell.md b/docs/shell.md
new file mode 100644
index 00000000..f453a1d0
--- /dev/null
+++ b/docs/shell.md
@@ -0,0 +1,117 @@
+# Shell Scripting
+
+Tomo comes with a built-in [lang](langs.md) called `Shell` for shell commands.
+This lets you write and invoke shell commands in a more type-safe way.
+
+```tomo
+user_name := ask("What's your name? ")
+_ := $Shell"echo Hello $user_name"
+```
+
+In the above example, there is no risk of code injection, because the
+user-controlled string is automatically escaped when performing interpolation.
+
+## Shell Methods
+
+### `by_line`
+
+**Description:**  
+Run a shell command and return an iterator over its output, line-by-line.
+
+**Signature:**  
+```tomo
+func by_line(command: Shell -> Void)
+```
+
+**Parameters:**
+
+- `command`: The command to run.
+
+**Returns:**  
+An optional iterator over the lines of the command's output. If the command fails
+to run, `none` will be returned.
+
+**Example:**  
+```tomo
+i := 1
+for line in $Shell"ping www.example.com":by_line()!:
+    stop if i > 5
+    i += 1
+```
+
+### `execute`
+
+**Description:**  
+Execute a shell command without capturing its output and return its exit status.
+
+**Signature:**  
+```tomo
+func execute(command: Shell -> Int32?)
+```
+
+**Parameters:**
+
+- `command`: The command to execute.
+
+**Returns:**  
+If the command exits normally, return its exit status. Otherwise return `none`.
+
+**Example:**  
+```tomo
+>> $Shell"touch file.txt":execute()
+= 0?
+```
+
+---
+
+### `run`
+
+**Description:**  
+Run a shell command and return the output text from `stdout`.
+
+**Signature:**  
+```tomo
+func run(command: Shell -> Text?)
+```
+
+**Parameters:**
+
+- `command`: The command to run.
+
+**Returns:**  
+If the program fails to run (e.g. a non-existent command), return `none`,
+otherwise return the entire standard output of the command as text. **Note:**
+if there is a trailing newline, it will be stripped.
+
+**Example:**  
+```tomo
+>> $Shell"seq 5":run()
+= "1$\n2$\n3$\n4$\n5"
+```
+
+---
+
+### `run_bytes`
+
+**Description:**  
+Run a shell command and return the output in raw bytes from `stdout`.
+
+**Signature:**  
+```tomo
+func run(command: Shell -> [Byte]?)
+```
+
+**Parameters:**
+
+- `command`: The command to run.
+
+**Returns:**  
+If the program fails to run (e.g. a non-existent command), return `none`,
+otherwise return the entire standard output of the command as an array of
+bytes.
+
+**Example:**  
+```tomo
+>> $Shell"seq 5":run_bytes()
+= [0x31, 0x0A, 0x32, 0x0A, 0x33, 0x0A, 0x34, 0x0A, 0x35, 0x0A]
+```