Add CLI ABI documentation

Closes https://github.com/rfjakob/gocryptfs/issues/77

1 files changed, 73 insertions, 0 deletions

diff --git a/Documentation/CLI_ABI.md b/Documentation/CLI_ABI.md
new file mode 100644
index 0000000..6930e83
--- /dev/null
+++ b/Documentation/CLI_ABI.md
@@ -0,0 +1,73 @@
+Stable CLI ABI
+==============
+
+If you want to call gocryptfs from your script or app, this is the
+stable ABI.
+
+General
+-------
+
+1. A password is piped into gocryptfs with an optional terminating
+   newline. Any unexpected data after the final newline will
+   cause gocryptfs to abort.
+2. Always pass "--" after the options. This prevents a CIPERDIR that
+   starts with a dash ("-") to wreak havoc.
+3. Use "-q" to get rid of all informational messages. Only error
+   messages (if any) will be printed to stderr (capture it!).
+4. Check the exit code of gocryptfs. 0 is success, anything else is an
+   error and details about that error will have been printed to stderr.
+
+Initialize Filesystem
+---------------------
+
+### Bash example
+
+    $ cat mypassword.txt | gocryptfs -init -q -- CIPHERDIR
+
+Content of "mypassword.txt":
+
+    mypassword1234
+
+### What you have to pipe to gocryptfs
+
+1. Password
+2. Optional newline
+
+### Notes
+
+1. The CIPHERDIR directory must exist and be empty
+
+Mount
+-----
+
+### Bash example
+
+    $ cat mypassword.txt | gocryptfs -q -- CIPHERDIR MOUNTPOINT
+
+### What you have to pipe to gocryptfs
+
+Same as for "Initialize Filesystem".
+
+### Notes
+
+1. The MOUNTPOINT directory must exist and be empty.
+
+Change Password
+---------------
+
+### Bash example
+
+    $ cat change.txt | gocryptfs -passwd -q -- CIPHERDIR
+
+Content of "change.txt":
+
+    mypassword1234
+    newpassword9876
+
+### What you have to pipe to gocryptfs
+
+1. Old password
+2. Newline
+3. New password
+4. Optional newline
+