Skip to content

Make docs clearer #182

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 24, 2020
Merged

Make docs clearer #182

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6720905
Make install instructions clearer & add some usage info
mrnugget Apr 23, 2020
3684a5a
Minor usage docs improvements
mrnugget Apr 23, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 61 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:

Expand All @@ -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! :)

Expand All @@ -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
```
Expand All @@ -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

Expand All @@ -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 ...
Expand All @@ -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.
Expand All @@ -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

Expand Down