From 67209050b8c79771c6f25f56bbf10a3e9d437118 Mon Sep 17 00:00:00 2001 From: Thorsten Ball Date: Thu, 23 Apr 2020 15:44:40 +0200 Subject: [PATCH 1/2] Make install instructions clearer & add some usage info --- README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 61 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index a94dcc0e1e..0e5109f016 100644 --- a/README.md +++ b/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) + -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:///.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:///.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:///.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:///.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 Sourcegraph + - `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 actions to generate patch sets + - `campaigns` - manages campaigns + - `lsif` - manages LSIF data + - `version` - display and compare the src-cli version against the recommended version - `your` instance + +Run `src -h` and `src -h` for more detailed usage information. ## Development From 3684a5ac3007e58ff667421616156765f628284e Mon Sep 17 00:00:00 2001 From: Thorsten Ball Date: Thu, 23 Apr 2020 15:59:26 +0200 Subject: [PATCH 2/2] Minor usage docs improvements --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 0e5109f016..83eda1108e 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,7 @@ To acquire the access token, visit your Sourcegraph instance (or https://sourceg `src` provides different subcommands to interact with different parts of Sourcegraph: - - `search` - search for results on 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 @@ -144,10 +144,10 @@ To acquire the access token, visit your Sourcegraph instance (or https://sourceg - `config` - manages global, org, and user settings - `extsvc` - manages external services - `extensions` (alias: `ext`) - manages extensions - - `actions` - runs actions to generate patch sets - - `campaigns` - manages campaigns + - `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 - `your` instance + - `version` - display and compare the src-cli version against the recommended version of the configured Sourcegraph instance Run `src -h` and `src -h` for more detailed usage information.