|
1 | | -# Sourcegraph CLI [](https://travis-ci.org/sourcegraph/src-cli) [](https://goreportcard.com/report/sourcegraph/src-cli) |
| 1 | +# [Sourcegraph](https://sourcegraph.com) CLI [](https://travis-ci.org/sourcegraph/src-cli) [](https://goreportcard.com/report/sourcegraph/src-cli) |
2 | 2 |
|
3 | | -<img src="https://user-images.githubusercontent.com/3173176/43567326-3db5f31c-95e6-11e8-9e74-4c04079c01b0.png" width=450 align=right> |
| 3 | +<img src="https://user-images.githubusercontent.com/3173176/43567326-3db5f31c-95e6-11e8-9e74-4c04079c01b0.png" width=500 align=right> |
4 | 4 |
|
5 | | -**Quick links**: |
6 | | -- [Installation](#installation) |
7 | | -- [Setup](#setup) ([Authentication](#authentication)) |
8 | | -- [Usage](#usage) |
| 5 | +`src` is a command line interface to Sourcegraph: |
9 | 6 |
|
10 | | -The Sourcegraph `src` CLI provides access to [Sourcegraph](https://sourcegraph.com) via a command-line interface. |
| 7 | +- **Search & get results in your terminal** |
| 8 | +- **Search & get JSON** for programmatic consumption |
| 9 | +- Make **GraphQL API requests** with auth easily & get JSON back fast |
| 10 | +- Execute **[campaign actions](https://docs.sourcegraph.com/user/campaigns)** |
| 11 | +- **Manage & administrate** repositories, users, and more |
| 12 | +- **Easily convert src-CLI commands to equivalent curl commands**, just add --get-curl! |
11 | 13 |
|
12 | | -It currently provides the ability to: |
13 | | - |
14 | | -- **Execute search queries** from the command line and get nice colorized output back (or JSON, optionally). |
15 | | -- **Execute GraphQL queries** against a Sourcegraph instance, and get JSON results back (`src api`). |
16 | | - - You can provide your API access token via an environment variable or file on disk. |
17 | | - - You can easily convert a `src api` command into a curl command with `src api -get-curl`. |
18 | | -- **Manage repositories, users, and organizations** using the `src repos`, `src users`, and `src orgs` commands. |
19 | | -- **Execute campaign actions** as part of [Sourcegraph campaigns](https://docs.sourcegraph.com/user/campaigns) |
20 | | - |
21 | | -If there is something you'd like to see Sourcegraph be able to do from the CLI, let us know! :) |
| 14 | +**Note:** Using Sourcegraph 3.12 or earlier? [See the older README](https://github.com/sourcegraph/src-cli/tree/3.11.2). |
22 | 15 |
|
23 | 16 | ## Installation |
24 | 17 |
|
25 | | -For Sourcegraph 3.13 and newer, the preferred method of installation is to ask _your_ Sourcegraph instance for the latest compatible version. To do this, replace `https://sourcegraph.com` in the commands below with the address of your instance. |
26 | | - |
27 | | -For Sourcegraph 3.12 and older, run the following commands verbatim (against sourcegraph.com) or install from one of the published [releases on GitHub](https://github.com/sourcegraph/src-cli/releases). |
28 | | - |
29 | | -``` |
30 | | -https://github.com/sourcegraph/src-cli/releases/download/{version}/{binary} |
31 | | -``` |
| 18 | +Binary downloads are available on the [releases tab](https://github.com/sourcegraph/src-cli/releases), and through Sourcegraph.com. _If the latest version does not work for you,_ consider using the version compatible with your Sourcegraph instance instead. |
32 | 19 |
|
33 | | -#### Requirements |
| 20 | +### Installation: Mac OS |
34 | 21 |
|
35 | | -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`. |
36 | | - |
37 | | -#### Mac OS |
| 22 | +#### Latest version |
38 | 23 |
|
39 | 24 | ```bash |
40 | | -# Sourcraph 3.13 and newer: |
41 | | -curl -L https://<your-sourcegraph-instance>/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src |
42 | | -chmod +x /usr/local/bin/src |
43 | | - |
44 | | -# Sourcraph 3.12 and older: |
45 | 25 | curl -L https://sourcegraph.com/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src |
46 | 26 | chmod +x /usr/local/bin/src |
47 | 27 | ``` |
48 | 28 |
|
49 | | -or use `brew` to get the newest version: |
| 29 | +or |
50 | 30 |
|
51 | | -``` |
| 31 | +```bash |
52 | 32 | brew install sourcegraph/src-cli/src-cli |
53 | 33 | ``` |
54 | 34 |
|
55 | | -#### Linux |
| 35 | +#### Version compatible with your Sourcegraph instance |
56 | 36 |
|
57 | | -```bash |
58 | | -# Sourcraph 3.13 and newer: |
59 | | -curl -L https://<your-sourcegraph-instance>/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src |
60 | | -chmod +x /usr/local/bin/src |
| 37 | +Replace `sourcegraph.example.com` with your Sourcegraph instance URL: |
61 | 38 |
|
62 | | -# Sourcraph 3.12 and older: |
63 | | -curl -L https://sourcegraph.com/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src |
| 39 | +```bash |
| 40 | +curl -L https://sourcegraph.example.com/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src |
64 | 41 | chmod +x /usr/local/bin/src |
65 | 42 | ``` |
66 | 43 |
|
67 | | -#### Windows |
68 | | - |
69 | | -**NOTE:** Windows support is still rough around the edges, but is available. If you encounter issues, please let us know by filing an issue :) |
70 | | - |
71 | | -Run in PowerShell as administrator: |
| 44 | +### Installation: Linux |
72 | 45 |
|
73 | | -```powershell |
74 | | -New-Item -ItemType Directory 'C:\Program Files\Sourcegraph' |
| 46 | +#### Latest version |
75 | 47 |
|
76 | | -# Sourcegraph 3.13 and newer: |
77 | | -Invoke-WebRequest https://<your-sourcegraph-instance>/.api/src-cli/src_windows_amd64.exe -OutFile 'C:\Program Files\Sourcegraph\src.exe' |
78 | | -# Sourcegraph 3.12 and older: |
79 | | -Invoke-WebRequest https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe -OutFile 'C:\Program Files\Sourcegraph\src.exe' |
80 | | -
|
81 | | -[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', [EnvironmentVariableTarget]::Machine) + ';C:\Program Files\Sourcegraph', [EnvironmentVariableTarget]::Machine) |
82 | | -$env:Path += ';C:\Program Files\Sourcegraph' |
| 48 | +```bash |
| 49 | +curl -L https://sourcegraph.com/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src |
| 50 | +chmod +x /usr/local/bin/src |
83 | 51 | ``` |
84 | 52 |
|
85 | | -Or manually: |
86 | | - |
87 | | -- Download the latest src_windows_amd64.exe: |
88 | | - - Sourcegraph 3.13 and newer: https://<your-sourcegraph-instance>/.api/src-cli/src_windows_amd64.exe |
89 | | - - Sourcegraph 3.12 and older: https://sourcegraph.com/.api/src-cli/src_windows_amd64.exe |
90 | | -- Place the file under e.g. `C:\Program Files\Sourcegraph\src.exe` |
91 | | -- Add that directory to your system path to access it from any command prompt |
| 53 | +#### Version compatible with your Sourcegraph instance |
92 | 54 |
|
93 | | -#### Renaming `src` (optional) |
| 55 | +Replace `sourcegraph.example.com` with your Sourcegraph instance URL: |
94 | 56 |
|
95 | | -If you have a naming conflict with the `src` command, such as a Bash alias, you can rename the static binary. For example, on Linux / Mac OS: |
96 | | - |
97 | | -```sh |
98 | | -mv /usr/local/bin/src /usr/local/bin/sourcegraph-cli |
| 57 | +```bash |
| 58 | +curl -L https://sourcegraph.example.com/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src |
| 59 | +chmod +x /usr/local/bin/src |
99 | 60 | ``` |
100 | 61 |
|
101 | | -You can then invoke it via `sourcegraph-cli`. |
| 62 | +### Installation: Windows |
102 | 63 |
|
103 | | -## Setup |
| 64 | +See [Sourcegraph CLI for Windows](WINDOWS.md). |
104 | 65 |
|
105 | | -To use `src` with your own Sourcegraph instance set the `SRC_ENDPOINT` environment variable: |
| 66 | +## Setup with your Sourcegraph instance |
106 | 67 |
|
107 | | -```sh |
108 | | -SRC_ENDPOINT=https://sourcegraph.example.com src search |
109 | | -``` |
| 68 | +### Via environment variables |
110 | 69 |
|
111 | | -Or via the configuration file (`~/src-config.json`): |
| 70 | +Point `src` to your instance and access token using environment variables: |
112 | 71 |
|
113 | 72 | ```sh |
114 | | -{"endpoint": "https://sourcegraph.example.com"} |
| 73 | +SRC_ENDPOINT=https://sourcegraph.example.com SRC_ACCESS_TOKEN="secret" src search 'foobar' |
115 | 74 | ``` |
116 | 75 |
|
117 | | -### Authentication |
| 76 | +### Via global configuration file |
118 | 77 |
|
119 | | -Some Sourcegraph instances will be configured to require authentication. You can do so via the environment variable `SRC_ACCESS_TOKEN`: |
| 78 | +Create a `$HOME/src-config.json` with: |
120 | 79 |
|
121 | 80 | ```sh |
122 | | -SRC_ENDPOINT=https://sourcegraph.example.com SRC_ACCESS_TOKEN="secret" src ... |
| 81 | +{"endpoint": "https://sourcegraph.example.com", "accessToken": "secret"} |
123 | 82 | ``` |
124 | 83 |
|
125 | | -Or via the configuration file (`~/src-config.json`): |
| 84 | +Then `src search 'foobar'` and other commands will automatically use that configuration! |
126 | 85 |
|
127 | | -```sh |
128 | | -{"accessToken": "secret", "endpoint": "https://sourcegraph.example.com"} |
129 | | -``` |
| 86 | +### Where to get an access token |
130 | 87 |
|
131 | | -See `src -h` for more information on specifying access tokens. |
132 | | - |
133 | | -To acquire the access token, visit your Sourcegraph instance (or https://sourcegraph.com), click your username in the top right to open the user menu, select **Settings**, and then select **Access tokens** in the left hand menu. |
| 88 | +Visit your Sourcegraph instance (or https://sourcegraph.com), click your username in the top right to open the user menu, select **Settings**, and then select **Access tokens** in the left hand menu. |
134 | 89 |
|
135 | 90 | ## Usage |
136 | 91 |
|
137 | 92 | `src` provides different subcommands to interact with different parts of Sourcegraph: |
138 | 93 |
|
139 | | - - `search` - search for results on the configured Sourcegraph instance |
140 | | - - `api` - interacts with the Sourcegraph GraphQL API |
141 | | - - `repos` (alias: `repo`) - manages repositories |
142 | | - - `users` (alias: `user`) - manages users |
143 | | - - `orgs` (alias: `org`) - manages organizations |
144 | | - - `config` - manages global, org, and user settings |
145 | | - - `extsvc` - manages external services |
146 | | - - `extensions` (alias: `ext`) - manages extensions |
147 | | - - `actions` - runs [campaign actions](https://docs.sourcegraph.com/user/campaigns/actions)to generate patch sets |
148 | | - - `campaigns` - manages [campaigns](https://docs.sourcegraph.com/user/campaigns) |
149 | | - - `lsif` - manages LSIF data |
150 | | - - `version` - display and compare the src-cli version against the recommended version of the configured Sourcegraph instance |
| 94 | + - `src search` - perform searches and get results in your terminal or as JSON |
| 95 | + - `src actions` - run [campaign actions](https://docs.sourcegraph.com/user/campaigns/actions) to generate patch sets |
| 96 | + - `src api` - run Sourcegraph GraphQL API requests |
| 97 | + - `src campaigns` - manages [campaigns](https://docs.sourcegraph.com/user/campaigns) |
| 98 | + - `src repos` - manage repositories |
| 99 | + - `src users` - manage users |
| 100 | + - `src orgs` - manages organization |
| 101 | + - `src config` - manage global, org, and user settings |
| 102 | + - `src extsvc` - manage external services (repository configuration) |
| 103 | + - `src extensions` - manage extensions |
| 104 | + - `src lsif` - manages LSIF data |
| 105 | + - `src version` - check version and guaranteed-compatible version for your Sourcegraph instance |
151 | 106 |
|
152 | 107 | Run `src -h` and `src <subcommand> -h` for more detailed usage information. |
153 | 108 |
|
154 | | -## Development |
| 109 | +#### Optional: Renaming `src` |
155 | 110 |
|
156 | | -If you want to develop the CLI, you can install it with `go get`: |
| 111 | +If you have a naming conflict with the `src` command, such as a Bash alias, you can rename the static binary. For example, on Linux / Mac OS: |
157 | 112 |
|
| 113 | +```sh |
| 114 | +mv /usr/local/bin/src /usr/local/bin/src-cli |
158 | 115 | ``` |
159 | | -go get -u github.com/sourcegraph/src-cli/cmd/src |
160 | | -``` |
161 | | - |
162 | | -## Releasing |
163 | | - |
164 | | -1. Find the latest version (either via the releases tab on GitHub or via git tags) to determine which version you are releasing. |
165 | | -2. `VERSION=9.9.9 ./release.sh` (replace `9.9.9` with the version you are releasing) |
166 | | -3. Travis will automatically perform the release. Once it has finished, **confirm that the curl commands fetch the latest version above**. |
167 | | -4. Update the `MinimumVersion` constant in the [src-cli package](https://github.com/sourcegraph/sourcegraph/tree/master/internal/src-cli/consts.go). |
168 | | - |
169 | | -### Patch releases |
170 | | - |
171 | | -If a backwards-compatible change is made _after_ a backwards-incompatible one, the backwards-compatible one should be re-released to older instances that support it. |
172 | | - |
173 | | -A Sourcegraph instance returns the highest patch version with the same major and minor version as `MinimumVersion` as defined in the instance. Patch versions are reserved solely for non-breaking changes and minor bug fixes. This allows us to dynamically release fixes for older versions of `src-cli` without having to update the instance. |
174 | | - |
175 | | -To release a bug fix or a new feature that is backwards compatible with one of the previous two minor version of Sourcegraph, cherry-pick the changes into a patch branch and re-releases with a new patch version. |
176 | | - |
177 | | -For example, suppose we have the the recommended versions. |
178 | | - |
179 | | -| Sourcegraph version | Recommended src-cli version | |
180 | | -| ------------------- | --------------------------- | |
181 | | -| `3.100` | `3.90.5` | |
182 | | -| `3.99` | `3.85.7` | |
183 | | - |
184 | | -If a new feature is added to a new `3.91.6` release of src-cli and this change requires only features available in Sourcegraph `3.99`, then this feature should also be present in a new `3.85.8` release of src-cli. Because a Sourcegraph instance will automatically select the highest patch version, all non-breaking changes should increment only the patch version. |
185 | 116 |
|
186 | | -Note that if instead the recommended src-cli version for Sourcegraph `3.99` was `3.90.4` in the example above, there is no additional step required, and the new patch version of src-cli will be available to both Sourcegraph versions. |
| 117 | +You can then invoke it via `src-cli`. |
0 commit comments