diff --git a/.assets/flow-diagram.dot b/.assets/flow-diagram.dot
new file mode 100644
index 0000000..eb95f9c
--- /dev/null
+++ b/.assets/flow-diagram.dot
@@ -0,0 +1,65 @@
+digraph {
+    rankdir=LR;
+    layout=dot;
+    node[shape=record];
+    
+    start[label="ssh sshportal";color=blue;fontcolor=blue;fontsize=20];
+    
+    subgraph cluster_sshportal {
+        graph[fontsize=20;style=dashed;color=purple;fontcolor=purple];
+        label="sshportal";
+        {
+            node[color=darkorange;fontcolor=darkorange];
+            known_user_key[label="known user key"];
+            unknown_user_key[label="unknown user key"];
+            invite_manager[label="invite manager"];
+            acl_manager[label="ACL manager"];
+        }
+        {
+            node[color=darkgreen;fontcolor=darkgreen];
+            builtin_shell[label="built-in shell"];
+            ssh_proxy[label="SSH proxy"];
+            learn_key[label="learn key"];
+        }
+        err_and_exit[label="error and exit";color=red;fontcolor=red];
+        { rank=same; ssh_proxy; builtin_shell; learn_key; err_and_exit; }
+        { rank=same; known_user_key; unknown_user_key; }
+    }
+    
+    subgraph cluster_hosts {
+        label="your hosts";
+        graph[fontsize=20;style=dashed;color=purple;fontcolor=purple];
+        node[color=blue;fontcolor=blue];
+        
+        host_1[label="root@host1"];
+        host_2[label="user@host2:2222"];
+        host_3[label="root@host3:1234"];
+    }
+    
+    {
+        edge[color=blue];
+        start -> known_user_key;
+        start -> unknown_user_key;
+        ssh_proxy -> host_1;
+        ssh_proxy -> host_2;
+        ssh_proxy -> host_3;
+    }
+    {
+        edge[color=darkgreen;fontcolor=darkgreen];
+        known_user_key -> builtin_shell[label="user=admin"];
+        acl_manager -> ssh_proxy[label="authorized"];
+        invite_manager -> learn_key[label="valid token"];
+    }
+    {
+        edge[color=darkorange;fontcolor=darkorange];
+        known_user_key -> acl_manager[label="user matches an existing host"];
+        unknown_user_key -> invite_manager[headlabel="user=invite:<token>"];
+    }
+    {
+        edge[color=red;fontcolor=red];
+        known_user_key -> err_and_exit[label="invalid user"];
+        acl_manager -> err_and_exit[label="unauthorized"];
+        unknown_user_key -> err_and_exit[label="any other user"];
+        invite_manager -> err_and_exit[label="invalid token"];
+    }
+}
\ No newline at end of file
diff --git a/.assets/flow-diagram.svg b/.assets/flow-diagram.svg
new file mode 100644
index 0000000..89298fd
--- /dev/null
+++ b/.assets/flow-diagram.svg
@@ -0,0 +1,188 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.40.1 (20161225.0304)
+ -->
+<!-- Title: %3 Pages: 1 -->
+<svg width="1026pt" height="312pt"
+ viewBox="0.00 0.00 1026.42 312.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 308)">
+<title>%3</title>
+<polygon fill="#ffffff" stroke="transparent" points="-4,4 -4,-308 1022.4219,-308 1022.4219,4 -4,4"/>
+<g id="clust1" class="cluster">
+<title>cluster_sshportal</title>
+<polygon fill="none" stroke="#a020f0" stroke-dasharray="5,2" points="147.7832,-8 147.7832,-296 858.9775,-296 858.9775,-8 147.7832,-8"/>
+<text text-anchor="middle" x="503.3804" y="-276" font-family="Times,serif" font-size="20.00" fill="#a020f0">sshportal</text>
+</g>
+<g id="clust6" class="cluster">
+<title>cluster_hosts</title>
+<polygon fill="none" stroke="#a020f0" stroke-dasharray="5,2" points="879.9775,-104 879.9775,-296 1010.4219,-296 1010.4219,-104 879.9775,-104"/>
+<text text-anchor="middle" x="945.1997" y="-276" font-family="Times,serif" font-size="20.00" fill="#a020f0">your hosts</text>
+</g>
+<!-- start -->
+<g id="node1" class="node">
+<title>start</title>
+<polygon fill="none" stroke="#0000ff" points="0,-118 0,-154 118.7832,-154 118.7832,-118 0,-118"/>
+<text text-anchor="middle" x="59.3916" y="-130" font-family="Times,serif" font-size="20.00" fill="#0000ff">ssh sshportal</text>
+</g>
+<!-- known_user_key -->
+<g id="node2" class="node">
+<title>known_user_key</title>
+<polygon fill="none" stroke="#ffa500" points="162.7832,-157 162.7832,-193 267.4316,-193 267.4316,-157 162.7832,-157"/>
+<text text-anchor="middle" x="215.1074" y="-170.8" font-family="Times,serif" font-size="14.00" fill="#ffa500">known user key</text>
+</g>
+<!-- start&#45;&gt;known_user_key -->
+<g id="edge1" class="edge">
+<title>start&#45;&gt;known_user_key</title>
+<path fill="none" stroke="#0000ff" d="M119.1501,-150.9669C130.1162,-153.7134 141.5894,-156.587 152.6326,-159.3528"/>
+<polygon fill="#0000ff" stroke="#0000ff" points="152.0758,-162.8214 162.6266,-161.8558 153.7765,-156.0311 152.0758,-162.8214"/>
+</g>
+<!-- unknown_user_key -->
+<g id="node3" class="node">
+<title>unknown_user_key</title>
+<polygon fill="none" stroke="#ffa500" points="155.7832,-72 155.7832,-108 274.4316,-108 274.4316,-72 155.7832,-72"/>
+<text text-anchor="middle" x="215.1074" y="-85.8" font-family="Times,serif" font-size="14.00" fill="#ffa500">unknown user key</text>
+</g>
+<!-- start&#45;&gt;unknown_user_key -->
+<g id="edge2" class="edge">
+<title>start&#45;&gt;unknown_user_key</title>
+<path fill="none" stroke="#0000ff" d="M119.1501,-118.3468C127.968,-115.7419 137.1138,-113.0401 146.1003,-110.3854"/>
+<polygon fill="#0000ff" stroke="#0000ff" points="147.1673,-113.7198 155.766,-107.5301 145.1841,-107.0066 147.1673,-113.7198"/>
+</g>
+<!-- acl_manager -->
+<g id="node5" class="node">
+<title>acl_manager</title>
+<polygon fill="none" stroke="#ffa500" points="514.7056,-173 514.7056,-209 609.8862,-209 609.8862,-173 514.7056,-173"/>
+<text text-anchor="middle" x="562.2959" y="-186.8" font-family="Times,serif" font-size="14.00" fill="#ffa500">ACL manager</text>
+</g>
+<!-- known_user_key&#45;&gt;acl_manager -->
+<g id="edge9" class="edge">
+<title>known_user_key&#45;&gt;acl_manager</title>
+<path fill="none" stroke="#ffa500" d="M267.461,-177.4127C331.1153,-180.3462 438.21,-185.2816 504.3082,-188.3277"/>
+<polygon fill="#ffa500" stroke="#ffa500" points="504.401,-191.8356 514.5516,-188.7997 504.7233,-184.843 504.401,-191.8356"/>
+<text text-anchor="middle" x="393.4697" y="-188.8" font-family="Times,serif" font-size="14.00" fill="#ffa500">user matches an existing host</text>
+</g>
+<!-- builtin_shell -->
+<g id="node6" class="node">
+<title>builtin_shell</title>
+<polygon fill="none" stroke="#006400" points="761.6929,-223 761.6929,-259 848.855,-259 848.855,-223 761.6929,-223"/>
+<text text-anchor="middle" x="805.2739" y="-236.8" font-family="Times,serif" font-size="14.00" fill="#006400">built&#45;in shell</text>
+</g>
+<!-- known_user_key&#45;&gt;builtin_shell -->
+<g id="edge6" class="edge">
+<title>known_user_key&#45;&gt;builtin_shell</title>
+<path fill="none" stroke="#006400" d="M267.592,-193.0548C281.6792,-197.2785 297.0081,-201.3215 311.4316,-204 469.5409,-233.361 660.2348,-239.5693 751.4965,-240.7835"/>
+<polygon fill="#006400" stroke="#006400" points="751.5568,-244.2844 761.5974,-240.9027 751.6394,-237.2848 751.5568,-244.2844"/>
+<text text-anchor="middle" x="562.2959" y="-238.8" font-family="Times,serif" font-size="14.00" fill="#006400">user=admin</text>
+</g>
+<!-- err_and_exit -->
+<g id="node9" class="node">
+<title>err_and_exit</title>
+<polygon fill="none" stroke="#ff0000" points="759.5703,-106 759.5703,-142 850.9775,-142 850.9775,-106 759.5703,-106"/>
+<text text-anchor="middle" x="805.2739" y="-119.8" font-family="Times,serif" font-size="14.00" fill="#ff0000">error and exit</text>
+</g>
+<!-- known_user_key&#45;&gt;err_and_exit -->
+<g id="edge11" class="edge">
+<title>known_user_key&#45;&gt;err_and_exit</title>
+<path fill="none" stroke="#ff0000" d="M267.4808,-170.4741C378.1362,-160.9117 634.8943,-138.7236 748.9418,-128.868"/>
+<polygon fill="#ff0000" stroke="#ff0000" points="749.5354,-132.3298 759.1969,-127.9818 748.9327,-125.3558 749.5354,-132.3298"/>
+<text text-anchor="middle" x="562.2959" y="-151.8" font-family="Times,serif" font-size="14.00" fill="#ff0000">invalid user</text>
+</g>
+<!-- invite_manager -->
+<g id="node4" class="node">
+<title>invite_manager</title>
+<polygon fill="none" stroke="#ffa500" points="512.5078,-17 512.5078,-53 612.084,-53 612.084,-17 512.5078,-17"/>
+<text text-anchor="middle" x="562.2959" y="-30.8" font-family="Times,serif" font-size="14.00" fill="#ffa500">invite manager</text>
+</g>
+<!-- unknown_user_key&#45;&gt;invite_manager -->
+<g id="edge10" class="edge">
+<title>unknown_user_key&#45;&gt;invite_manager</title>
+<path fill="none" stroke="#ffa500" d="M274.7912,-80.5452C338.467,-70.4579 438.7527,-54.5711 502.4793,-44.4759"/>
+<polygon fill="#ffa500" stroke="#ffa500" points="503.0528,-47.9288 512.382,-42.9071 501.9575,-41.015 503.0528,-47.9288"/>
+<text text-anchor="middle" x="455.4386" y="-31.7071" font-family="Times,serif" font-size="14.00" fill="#ffa500">user=invite:&lt;token&gt;</text>
+</g>
+<!-- unknown_user_key&#45;&gt;err_and_exit -->
+<g id="edge13" class="edge">
+<title>unknown_user_key&#45;&gt;err_and_exit</title>
+<path fill="none" stroke="#ff0000" d="M274.4978,-89.2935C352.2933,-89.0083 492.8294,-90.6942 612.084,-104 628.7169,-105.8558 632.5001,-108.7473 649.084,-111 682.1267,-115.4884 719.327,-118.6586 749.132,-120.7442"/>
+<polygon fill="#ff0000" stroke="#ff0000" points="749.133,-124.2522 759.347,-121.437 749.6068,-117.2683 749.133,-124.2522"/>
+<text text-anchor="middle" x="562.2959" y="-106.8" font-family="Times,serif" font-size="14.00" fill="#ff0000">any other user</text>
+</g>
+<!-- learn_key -->
+<g id="node8" class="node">
+<title>learn_key</title>
+<polygon fill="none" stroke="#006400" points="771.4272,-17 771.4272,-53 839.1206,-53 839.1206,-17 771.4272,-17"/>
+<text text-anchor="middle" x="805.2739" y="-30.8" font-family="Times,serif" font-size="14.00" fill="#006400">learn key</text>
+</g>
+<!-- invite_manager&#45;&gt;learn_key -->
+<g id="edge8" class="edge">
+<title>invite_manager&#45;&gt;learn_key</title>
+<path fill="none" stroke="#006400" d="M612.3465,-35C656.1463,-35 719.1598,-35 761.1155,-35"/>
+<polygon fill="#006400" stroke="#006400" points="761.3041,-38.5001 771.3041,-35 761.304,-31.5001 761.3041,-38.5001"/>
+<text text-anchor="middle" x="685.8271" y="-37.8" font-family="Times,serif" font-size="14.00" fill="#006400">valid token</text>
+</g>
+<!-- invite_manager&#45;&gt;err_and_exit -->
+<g id="edge14" class="edge">
+<title>invite_manager&#45;&gt;err_and_exit</title>
+<path fill="none" stroke="#ff0000" d="M611.4661,-53.0105C651.6045,-67.7127 708.3017,-88.4802 750.0066,-103.7562"/>
+<polygon fill="#ff0000" stroke="#ff0000" points="748.8708,-107.0676 759.4646,-107.2206 751.2785,-100.4946 748.8708,-107.0676"/>
+<text text-anchor="middle" x="685.8271" y="-95.8" font-family="Times,serif" font-size="14.00" fill="#ff0000">invalid token</text>
+</g>
+<!-- ssh_proxy -->
+<g id="node7" class="node">
+<title>ssh_proxy</title>
+<polygon fill="none" stroke="#006400" points="766.3516,-168 766.3516,-204 844.1963,-204 844.1963,-168 766.3516,-168"/>
+<text text-anchor="middle" x="805.2739" y="-181.8" font-family="Times,serif" font-size="14.00" fill="#006400">SSH proxy</text>
+</g>
+<!-- acl_manager&#45;&gt;ssh_proxy -->
+<g id="edge7" class="edge">
+<title>acl_manager&#45;&gt;ssh_proxy</title>
+<path fill="none" stroke="#006400" d="M610.0008,-192.3563C641.8818,-193.0022 684.7518,-193.37 722.5703,-192 733.3636,-191.609 744.9337,-190.9319 755.8983,-190.1699"/>
+<polygon fill="#006400" stroke="#006400" points="756.4612,-193.6382 766.18,-189.4199 755.9519,-186.6568 756.4612,-193.6382"/>
+<text text-anchor="middle" x="685.8271" y="-194.8" font-family="Times,serif" font-size="14.00" fill="#006400">authorized</text>
+</g>
+<!-- acl_manager&#45;&gt;err_and_exit -->
+<g id="edge12" class="edge">
+<title>acl_manager&#45;&gt;err_and_exit</title>
+<path fill="none" stroke="#ff0000" d="M610.264,-178.009C646.3866,-168.197 697.1155,-154.3556 741.5703,-142 744.1794,-141.2748 746.8478,-140.5307 749.5426,-139.7772"/>
+<polygon fill="#ff0000" stroke="#ff0000" points="750.6733,-143.0952 759.3567,-137.025 748.7831,-136.3552 750.6733,-143.0952"/>
+<text text-anchor="middle" x="685.8271" y="-169.8" font-family="Times,serif" font-size="14.00" fill="#ff0000">unauthorized</text>
+</g>
+<!-- host_1 -->
+<g id="node10" class="node">
+<title>host_1</title>
+<polygon fill="none" stroke="#0000ff" points="904.3086,-223 904.3086,-259 986.0908,-259 986.0908,-223 904.3086,-223"/>
+<text text-anchor="middle" x="945.1997" y="-236.8" font-family="Times,serif" font-size="14.00" fill="#0000ff">root@host1</text>
+</g>
+<!-- ssh_proxy&#45;&gt;host_1 -->
+<g id="edge3" class="edge">
+<title>ssh_proxy&#45;&gt;host_1</title>
+<path fill="none" stroke="#0000ff" d="M844.2511,-201.3206C859.7986,-207.4318 877.9046,-214.5486 894.4551,-221.054"/>
+<polygon fill="#0000ff" stroke="#0000ff" points="893.4017,-224.4006 903.9889,-224.8015 895.9624,-217.8858 893.4017,-224.4006"/>
+</g>
+<!-- host_2 -->
+<g id="node11" class="node">
+<title>host_2</title>
+<polygon fill="none" stroke="#0000ff" points="887.9775,-168 887.9775,-204 1002.4219,-204 1002.4219,-168 887.9775,-168"/>
+<text text-anchor="middle" x="945.1997" y="-181.8" font-family="Times,serif" font-size="14.00" fill="#0000ff">user@host2:2222</text>
+</g>
+<!-- ssh_proxy&#45;&gt;host_2 -->
+<g id="edge4" class="edge">
+<title>ssh_proxy&#45;&gt;host_2</title>
+<path fill="none" stroke="#0000ff" d="M844.2511,-186C854.6959,-186 866.2954,-186 877.8023,-186"/>
+<polygon fill="#0000ff" stroke="#0000ff" points="877.8592,-189.5001 887.8591,-186 877.8591,-182.5001 877.8592,-189.5001"/>
+</g>
+<!-- host_3 -->
+<g id="node12" class="node">
+<title>host_3</title>
+<polygon fill="none" stroke="#0000ff" points="888.3638,-113 888.3638,-149 1002.0356,-149 1002.0356,-113 888.3638,-113"/>
+<text text-anchor="middle" x="945.1997" y="-126.8" font-family="Times,serif" font-size="14.00" fill="#0000ff">root@host3:1234</text>
+</g>
+<!-- ssh_proxy&#45;&gt;host_3 -->
+<g id="edge5" class="edge">
+<title>ssh_proxy&#45;&gt;host_3</title>
+<path fill="none" stroke="#0000ff" d="M844.2511,-170.6794C858.381,-165.1255 874.624,-158.7409 889.8921,-152.7395"/>
+<polygon fill="#0000ff" stroke="#0000ff" points="891.2185,-155.9789 899.245,-149.0632 888.6578,-149.4641 891.2185,-155.9789"/>
+</g>
+</g>
+</svg>
diff --git a/Makefile b/Makefile
index df9c077..b3a36a6 100644
--- a/Makefile
+++ b/Makefile
@@ -44,3 +44,4 @@ backup:
 doc:
 	dot -Tsvg ./.assets/overview.dot > ./.assets/overview.svg
 	dot -Tsvg ./.assets/cluster-mysql.dot > ./.assets/cluster-mysql.svg
+	dot -Tsvg ./.assets/flow-diagram.dot > ./.assets/flow-diagram.svg
diff --git a/README.md b/README.md
index 473511e..fb43d50 100644
--- a/README.md
+++ b/README.md
@@ -129,7 +129,11 @@ To associate this account with a key, use the following SSH user: 'invite:NfHK5a
 config>
 ```
 
-## CLI
+## Flow Diagram
+
+![Flow Diagram](https://raw.github.com/moul/sshportal/master/.assets/flow-diagram.svg?sanitize=true)
+
+## built-in shell
 
 `sshportal` embeds a configuration CLI.