diff --git a/readme.md b/readme.md
index 902a21d..eedc4af 100644
--- a/readme.md
+++ b/readme.md
@@ -8,22 +8,49 @@ Cardiograph is an imaginary computer. It has three main components:
 
 ## Simulator
 
-### Run assembler
-
-```./assembler.js source_code.asm [output.txt]```
-
-By default, the output is written to `out.txt`. It is saved as a string of space-separated decimal numbers.
-
-
-### Run simulator
-
-```./cardiograph.js < machine_code.txt```
-
 ### Dependencies
 
 - Node.js
 
 
+### Quick examples
+
+Assemble and run:  
+```./assembler.js -i <source.asm> | cardiograph.js```
+
+Assemble to a file:  
+```./assembler.js -i <source.asm> -o <machinecode.out>```
+
+Run from a file:  
+```./cardiograph.js -i <machinecode.out>```
+
+
+### Assembler: assembler.js
+
+```
+Usage: ./assembler.js [-a] -i <input-file> [-o <output-file>]
+
+-a, --annotate      Output code with debugging annotations
+-i, --in <file>     Assembly-language input
+-o, --out <file>    Machine-code output
+```
+
+- If an output file is not provided, the output is printed to stdout
+
+- If the `annotate` flag is not set, the machine code is returned as a string of space-separated decimal numbers
+
+
+### Simulator: cardiograph.js
+
+```
+Usage: ./cardiograph.js [-i <file>]
+
+-i, --in <file>    Machine-code input
+```
+
+- If an input file is not provided, the input is read from stdin
+
+
 ## CPU
 
 ### Registers and Flags