Improve cli doc

Author: hugoduncan

README.md

@@ -10,30 +10,34 @@ The `clj-ssh.cli` namespace provides some functions for ease of use at the REPL.
 
     (use 'clj-ssh.ssh)
 
-There is a simple `ssh` function, which by default, will use the system
-ssh-agent.
+Use `ssh` to execute a command, say `ls`, on a remote host \"my-host\",
 
-    (ssh "hostname" "ls")
+    (ssh \"my-host\" \"ls\")
+      => {:exit 0 :out \"file1\\nfile2\\n\" :err \"\")
 
-Strict host key checking can be turned off.
+By default this will use the system ssh-agent to obtain your ssh keys, and it
+uses your current username, but this can be specified:
 
-    (default-session-options {:strict-host-key-checking :no})
+    (ssh \"my-host\" \"ls\" :username \"remote-user\")
+      => {:exit 0 :out \"file1\\nfile2\\n\" :err \"\")
 
-By default, your current username is used.  If your key has a passphrase, and
-you are on OSX, then you should be asked for access to your keychain.  If you
-are on any other OS without a ssh-agent, you will need to explicitly add your
-key to the clj-ssh's ssh-agent with the appropriate add-identity call.
+Strict host key checking can be turned off:
 
-SFTP is supported:
+    (default-session-options {:strict-host-key-checking :no})
 
-```clj
-(sftp "hostname" :put "/from/this/path" "to/this/path")
-```
+SFTP is also supported. For example, to copy a local file to a remote host
+\"my-host\":
+
+    (sftp \"my-host\" :put \"/from/this/path\" \"to/this/path\")
 
 Note that any sftp commands that change the state of the sftp session (such as
 cd) do not work with the simplified interface, as a new session is created each
 time.
 
+If your key has a passphrase, you will need to explicitly add your key either to
+the system's ssh-agent, or to clj-ssh's ssh-agent with the appropriate
+`add-identity` call.
+
 ### Non REPL
 
 The `clj-ssh.ssh` namespace should be using SSH from functional code.

src/clj_ssh/cli.clj

@@ -1,27 +1,35 @@
 (ns clj-ssh.cli
   "Provides a REPL friendly interface for clj-ssh.
 
-There is a simple `ssh` function, which by default, will use the system
-ssh-agent.
+    (use 'clj-ssh.cli)
 
-    (ssh \"hostname\" \"ls\")
+Use `ssh` to execute a command, say `ls`, on a remote host \"my-host\",
 
-Strict host key checking can be turned off.
+    (ssh \"my-host\" \"ls\")
+      => {:exit 0 :out \"file1\\nfile2\\n\" :err \"\")
 
-    (default-session-options {:strict-host-key-checking :no})
+By default this will use the system ssh-agent to obtain your ssh keys, and it
+uses your current username, but this can be specified:
+
+    (ssh \"my-host\" \"ls\" :username \"remote-user\")
+      => {:exit 0 :out \"file1\\nfile2\\n\" :err \"\")
 
-By default, your current username is used.  If your key has a passphrase, and
-you are on OSX, then you should be asked for access to your keychain.  If you
-are on any other OS without a ssh-agent, you will need to explicitly add your
-key to the clj-ssh's ssh-agent with the appropriate add-identity call.
+Strict host key checking can be turned off:
 
-SFTP is supported:
+    (default-session-options {:strict-host-key-checking :no})
 
-    (sftp \"hostname\" :put \"/from/this/path\" \"to/this/path\")
+SFTP is also supported. For example, to copy a local file to a remote host
+\"my-host\":
+
+    (sftp \"my-host\" :put \"/from/this/path\" \"to/this/path\")
 
 Note that any sftp commands that change the state of the sftp session (such as
 cd) do not work with the simplified interface, as a new session is created each
-time."
+time.
+
+If your key has a passphrase, you will need to explicitly add your key either to
+the system's ssh-agent, or to clj-ssh's ssh-agent with the appropriate
+`add-identity` call."
   (:require
    [clj-ssh.ssh :as ssh]
    [clojure.string :as string]))