From 20b5c517ba6f13645d6af1b3dd4caffed13294dc Mon Sep 17 00:00:00 2001
From: Mars Hall <mars@users.noreply.github.com>
Date: Thu, 19 Dec 2019 15:02:49 -0800
Subject: [PATCH] Add direct usage info to README

---
 README.md | 42 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 38 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 6377ff0..186e0d7 100755
--- a/README.md
+++ b/README.md
@@ -4,11 +4,45 @@ This is the official [Heroku buildpack](http://devcenter.heroku.com/articles/bui
 
 ## Usage
 
-To use `sfdx` and `jq`, you simply need to export the appropriate paths:
+This buildpack adds `sfdx` & `jq` the `$PATH` in the dyno, so that they are immediately usable.
 
+In the following commands:  
+✏️ *Replace `$ORG_USERNAME` with the target org's username or sfdx alias.*  
+✏️ *Replace `$APP_NAME` with the target Heroku app's name.*
+
+**To enable automated authentication with a Salesforce org** add its secret refresh token `sfdxAuthUrl` to the Heroku app:
+
+```bash
+heroku config:set --app $APP_NAME SFDX_AUTH_URL="$(sfdx force:org:display -u "$ORG_USERNAME" --verbose --json | jq -r .result.sfdxAuthUrl)"
+```
+
+Then, create a `.profile` file with the following contents, and commit/deploy it to the Heroku app. Everytime a dyno starts-up, this script will read that secret value to authenticate `sfdx` with the org:
+
+```bash
+#!/bin/bash
+
+# Write config var to a file for sfdx
+echo "$SFDX_AUTH_URL" > sfdx-auth-url.txt
+
+# Authenticate sfdx with the org
+sfdx force:auth:sfdxurl:store -f sfdx-auth-url.txt -s
+
+# Delete the secret material
+rm sfdx-auth-url.txt
 ```
-export PATH="$BUILD_DIR/vendor/sfdx/cli/bin:$PATH"
-export PATH="$BUILD_DIR/vendor/sfdx/jq:$PATH"
+
+Finally, verify that authentication is working using a one-off dyno:
+
+```bash
+heroku run bash --app $APP_NAME
+~ $ sfdx force:org:list
+=== Orgs
+     USERNAME           ORG ID              CONNECTED STATUS
+───  ─────────────────  ──────────────────  ────────────────
+(U)  xxxxx@example.com  00D6g000000XXXXXXX  Connected
+
+No active scratch orgs found. Specify --all to see all scratch orgs
 ```
 
-The `$BUILD_DIR` is the path where your apps source is stored on the Heroku dyno.
\ No newline at end of file
+🏁 Once finished, the Heroku app's `sfdx` CLI will maintain authentication with the Salesforce org
+