From 54caaf4b980e0432baef54c5129aa53c43be70e8 Mon Sep 17 00:00:00 2001
From: Jakob Unterwurzacher <jakobunt@gmail.com>
Date: Sun, 12 Feb 2017 19:12:02 +0100
Subject: [PATCH] Add CLI ABI documentation

Closes https://github.com/rfjakob/gocryptfs/issues/77
---
 Documentation/CLI_ABI.md | 73 ++++++++++++++++++++++++++++++++++++++++
 README.md                |  7 ++++
 2 files changed, 80 insertions(+)
 create mode 100644 Documentation/CLI_ABI.md

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
+
diff --git a/README.md b/README.md
index f130c52..905c3c0 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,13 @@ The [MANPAGE.md](Documentation/MANPAGE.md) containes a description of available
 If you already have gocryptfs installed, run `./MANPAGE-render.bash` to bring up the rendered manpage in
 your man pager (requires pandoc).
 
+Stable CLI ABI
+--------------
+
+If you want to call gocryptfs from your app or script, see
+[CLI_ABI.md](Documentation/CLI_ABI.md) for the official stable
+ABI. This ABI is regression-tested by the test suite.
+
 Storage Overhead
 ----------------