Make docs clearer (#182)

* Make install instructions clearer & add some usage info

* Minor usage docs improvements

Author: mrnugget

README.md

@@ -1,10 +1,13 @@
-# Sourcegraph CLI [![Build Status](https://travis-ci.org/sourcegraph/src-cli.svg)](https://travis-ci.org/sourcegraph/src-cli) [![Build status](https://ci.appveyor.com/api/projects/status/fwa1bkd198hyim8a?svg=true)](https://ci.appveyor.com/project/sourcegraph/src-cli) [![Go Report Card](https://goreportcard.com/badge/sourcegraph/src-cli)](https://goreportcard.com/report/sourcegraph/src-cli)
+# Sourcegraph CLI [![Build Status](https://travis-ci.org/sourcegraph/src-cli.svg)](https://travis-ci.org/sourcegraph/src-cli) [![Go Report Card](https://goreportcard.com/badge/sourcegraph/src-cli)](https://goreportcard.com/report/sourcegraph/src-cli)
 
-**Quick links**: [Installation](#installation), [Setup](#setup) ([Authentication](#authentication)), [Usage](#usage)
+<img src="https://user-images.githubusercontent.com/3173176/43567326-3db5f31c-95e6-11e8-9e74-4c04079c01b0.png" style="max-width: 350px; float: right;" >
 
-The Sourcegraph `src` CLI provides access to [Sourcegraph](https://sourcegraph.com) via a command-line interface.
+**Quick links**:
+- [Installation](#installation)
+- [Setup](#setup) ([Authentication](#authentication))
+- [Usage](#usage)
 
-![image](https://user-images.githubusercontent.com/3173176/43567326-3db5f31c-95e6-11e8-9e74-4c04079c01b0.png)
+The Sourcegraph `src` CLI provides access to [Sourcegraph](https://sourcegraph.com) via a command-line interface.
 
 It currently provides the ability to:
 
@@ -13,6 +16,7 @@ It currently provides the ability to:
   - You can provide your API access token via an environment variable or file on disk.
   - You can easily convert a `src api` command into a curl command with `src api -get-curl`.
 - **Manage repositories, users, and organizations** using the `src repos`, `src users`, and `src orgs` commands.
+- **Execute campaign actions** as part of [Sourcegraph campaigns](https://docs.sourcegraph.com/user/campaigns)
 
 If there is something you'd like to see Sourcegraph be able to do from the CLI, let us know! :)
 
@@ -24,20 +28,38 @@ For Sourcegraph 3.12 and older, run the following commands verbatim (against sou
 
 ```
 https://github.com/sourcegraph/src-cli/releases/download/{version}/{binary}
-````
+```
 
-> NOTE: If you want to use the 'src actions exec' functionality, make sure that git is installed and accessible by src.
+#### Requirements
+
+If you want to use the `src action exec` functionality (see [Sourcegraph campaigns](https://docs.sourcegraph.com/user/campaigns) docs and `src action exec -h`), make sure that `git` is installed and accessible by `src`.
 
 #### Mac OS
 
 ```bash
+# Sourcraph 3.13 and newer:
+curl -L https://<your-sourcegraph-instance>/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src
+chmod +x /usr/local/bin/src
+
+# Sourcraph 3.12 and older:
 curl -L https://sourcegraph.com/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src
 chmod +x /usr/local/bin/src
 ```
 
+or use `brew` to get the newest version:
+
+```
+brew install sourcegraph/src-cli/src-cli
+```
+
 #### Linux
 
 ```bash
+# Sourcraph 3.13 and newer:
+curl -L https://<your-sourcegraph-instance>/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src
+chmod +x /usr/local/bin/src
+
+# Sourcraph 3.12 and older:
 curl -L https://sourcegraph.com/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src
 chmod +x /usr/local/bin/src
 ```
@@ -50,14 +72,21 @@ Run in PowerShell as administrator:
 
 ```powershell
 New-Item -ItemType Directory 'C:\Program Files\Sourcegraph'
+
+# Sourcegraph 3.13 and newer:
+Invoke-WebRequest https://<your-sourcegraph-instance>/.api/src-cli/src_windows_amd64.exe -OutFile 'C:\Program Files\Sourcegraph\src.exe'
+# Sourcegraph 3.12 and older:
 Invoke-WebRequest https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe -OutFile 'C:\Program Files\Sourcegraph\src.exe'
+
 [Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', [EnvironmentVariableTarget]::Machine) + ';C:\Program Files\Sourcegraph', [EnvironmentVariableTarget]::Machine)
 $env:Path += ';C:\Program Files\Sourcegraph'
 ```
 
 Or manually:
 
-- Download the latest src_windows_amd64.exe: https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe and rename to `src.exe`.
+- Download the latest src_windows_amd64.exe:
+  - Sourcegraph 3.13 and newer: https://<your-sourcegraph-instance>/.api/src-cli/src_windows_amd64.exe
+  - Sourcegraph 3.12 and older: https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe
 - Place the file under e.g. `C:\Program Files\Sourcegraph\src.exe`
 - Add that directory to your system path to access it from any command prompt
 
@@ -73,15 +102,21 @@ You can then invoke it via `sourcegraph-cli`.
 
 ## Setup
 
-If you want to use `src` with your own Sourcegraph instance set the `SRC_ENDPOINT` environment variable:
+To use `src` with your own Sourcegraph instance set the `SRC_ENDPOINT` environment variable:
 
 ```sh
 SRC_ENDPOINT=https://sourcegraph.example.com src search
 ```
 
+Or via the configuration file (`~/src-config.json`):
+
+```sh
+{"endpoint": "https://sourcegraph.example.com"}
+```
+
 ### Authentication
 
-Some Sourcegraph instances will be configured to require authentication. You can do so via the environment:
+Some Sourcegraph instances will be configured to require authentication. You can do so via the environment variable `SRC_ACCESS_TOKEN`:
 
 ```sh
 SRC_ENDPOINT=https://sourcegraph.example.com SRC_ACCESS_TOKEN="secret" src ...
@@ -90,7 +125,7 @@ SRC_ENDPOINT=https://sourcegraph.example.com SRC_ACCESS_TOKEN="secret" src ...
 Or via the configuration file (`~/src-config.json`):
 
 ```sh
-	{"accessToken": "secret", "endpoint": "https://sourcegraph.example.com"}
+{"accessToken": "secret", "endpoint": "https://sourcegraph.example.com"}
 ```
 
 See `src -h` for more information on specifying access tokens.
@@ -99,7 +134,22 @@ To acquire the access token, visit your Sourcegraph instance (or https://sourceg
 
 ## Usage
 
-Consult `src -h` and `src api -h` for usage information.
+`src` provides different subcommands to interact with different parts of Sourcegraph:
+
+ - `search` - search for results on the configured Sourcegraph instance
+ - `api` - interacts with the Sourcegraph GraphQL API
+ - `repos` (alias: `repo`) - manages repositories
+ - `users` (alias: `user`) - manages users
+ - `orgs` (alias: `org`) - manages organizations
+ - `config` - manages global, org, and user settings
+ - `extsvc` - manages external services
+ - `extensions` (alias: `ext`) - manages extensions
+ - `actions` - runs [campaign actions](https://docs.sourcegraph.com/user/campaigns/actions)to generate patch sets
+ - `campaigns` - manages [campaigns](https://docs.sourcegraph.com/user/campaigns)
+ - `lsif` - manages LSIF data
+ - `version` - display and compare the src-cli version against the recommended version of the configured Sourcegraph instance
+
+Run `src -h` and `src <subcommand> -h` for more detailed usage information.
 
 ## Development