github.com/jfrog/jfrog-cli-go@v1.22.1-0.20200318093948-4826ef344ffd/README.md (about) 1 |Branch|Status| 2 |:---:|:---:| 3 |master|[](https://ci.appveyor.com/project/jfrog-ecosystem/jfrog-cli-go/branch/master) 4 |dev|[](https://ci.appveyor.com/project/jfrog-ecosystem/jfrog-cli-go/branch/dev)| 5 6 # Table of Contents 7 - [Overview](#overview) 8 - [Download and Installation](#download-and-installation) 9 - [Building the Executable](#building-the-executable) 10 - [Tests](#tests) 11 - [Code Contributions](#code-contributions) 12 - [Using JFrog CLI](#using-jfrog-cli) 13 - [Release Notes](#release-notes) 14 15 # Overview 16 JFrog CLI is a compact and smart client that provides a simple interface that automates access to *Artifactory*, *Bintray* and *Mission Control* through their respective REST APIs. 17 By using the JFrog CLI, you can greatly simplify your automation scripts making them more readable and easier to maintain. 18 Several features of the JFrog CLI makes your scripts more efficient and reliable: 19 20 - Multi-threaded upload and download of artifacts make builds run faster 21 - Checksum optimization reduces redundant file transfers 22 - Wildcards and regular expressions give you an easy way to collect all the artifacts you wish to upload or download. 23 - "Dry run" gives you a preview of file transfer operations before you actually run them 24 25 # Download and Installation 26 27 You can download the executable directly using the [JFrog CLI Download Page](https://www.jfrog.com/getcli/), or install it with npm, homebrew or docker. 28 ## NPM 29 ```` 30 npm install jfrog-cli-go 31 ```` 32 ## Homebrew 33 ```` 34 brew install jfrog-cli-go 35 ```` 36 ## Docker 37 ```` 38 docker run docker.bintray.io/jfrog/jfrog-cli-go:latest jfrog <COMMAND> 39 ```` 40 41 # Building the Executable 42 43 JFrog CLI is written in the [Go programming language](https://golang.org/), so to build the CLI yourself, you first need to have Go installed and configured on your machine. 44 45 ## Install Go 46 47 To download and install `Go`, please refer to the [Go documentation](https://golang.org/doc/install). 48 Please download `Go 1.14.x` or above. 49 50 ## Download and Build the CLI 51 52 Navigate to a directory where you want to create the jfrog-cli-go project, **outside** the `$GOPATH` tree. 53 54 If the `GOPATH` variable is unset, it's default value is the go folder under the user home. 55 56 Verify that the `GO111MODULE` variable is either unset, or explicitly set to `auto`. 57 58 Clone the jfrog-cli project by executing the following command: 59 ```` 60 git clone https://github.com/jfrog/jfrog-cli 61 ```` 62 Build the project by navigating to the jfrog folder and executing the following commands. 63 On Unix based systems run: 64 ```` 65 cd jfrog-cli 66 ./build.sh 67 ```` 68 On Windows run: 69 ```` 70 cd jfrog-cli 71 build.bat 72 ```` 73 Once completed, you will find the JFrog CLI executable at your current directory. 74 75 # Tests 76 ### Usage 77 ```` 78 go test -v github.com/jfrog/jfrog-cli-go [test-types] [flags] 79 ```` 80 81 The flags are: 82 83 | Flag | Description | 84 | --- | --- | 85 | `-rt.url` | [Default: http://localhost:8081/artifactory] Artifactory URL. | 86 | `-rt.user` | [Default: admin] Artifactory username.| 87 | `-rt.password` | [Default: password] Artifactory password. | 88 | `-rt.apikey` | Artifactory API key. | 89 | `-rt.accessToken` | Artifactory access token. | 90 91 The types are: 92 93 | Type | Description | 94 | --- | --- | 95 | `-test.artifactory` | Artifactory tests | 96 | `-test.npm` | Npm tests | 97 | `-test.maven` | Maven tests | 98 | `-test.gradle` | Gradle tests | 99 | `-test.docker` | Docker tests | 100 | `-test.go` | Go tests | 101 | `-test.pip` | Pip tests | 102 | `-test.nuget` | Nuget tests | 103 104 * Running the tests will create two repositories: `jfrog-cli-tests-repo` and `jfrog-cli-tests-repo1`.<br/> 105 Once the tests are completed, the content of these repositories will be deleted. 106 107 #### Artifactory tests 108 In addition to [general optional flags](#Usage) you can use the following optional artifactory flags. 109 110 | Flag | Description | 111 | --- | --- | 112 | `-rt.sshKeyPath` | [Optional] Ssh key file path. Should be used only if the Artifactory URL format is ssh://[domain]:port. | 113 | `-rt.sshPassphrase` | [Optional] Ssh key passphrase. | 114 115 116 ##### Examples 117 To run artifactory tests execute the following command. 118 ```` 119 go test -v github.com/jfrog/jfrog-cli-go -test.artifactory [flags] 120 ```` 121 122 #### Npm tests 123 ##### Requirement 124 * The *npm* executables should be included as part of the *PATH* environment variable. 125 126 ##### Limitation 127 * Currently, npm integration support only http(s) connections to Artifactory using username and password. 128 129 ##### Examples 130 To run npm tests execute the following command. 131 ```` 132 go test -v github.com/jfrog/jfrog-cli-go -test.npm [flags] 133 ```` 134 135 #### Maven tests 136 ##### Requirements 137 * The *M2_HOME* environment variable should be set to the local maven installation path. 138 * The *java* executable should be included as part of the *PATH* environment variable. Alternatively, set the *JAVA_HOME* environment variable. 139 140 ##### Limitation 141 * Currently, maven integration support only http(s) connections to Artifactory using username and password. 142 143 ##### Examples 144 To run maven tests execute the following command. 145 ```` 146 go test -v github.com/jfrog/jfrog-cli-go -test.maven [flags] 147 ```` 148 149 #### Gradle tests 150 ##### Requirements 151 * The *gradle* executables should be included as part of the *PATH* environment variable. 152 * The *java* executable should be included as part of the *PATH* environment variable. Alternatively, set the *JAVA_HOME* environment variable. 153 154 ##### Limitation 155 * Currently, gradle integration support only http(s) connections to Artifactory using username and password. 156 157 ##### Examples 158 To run gradle tests execute the following command. 159 ```` 160 go test -v github.com/jfrog/jfrog-cli-go -test.gradle [flags] 161 ```` 162 163 #### Docker tests 164 In addition to [general optional flags](#Usage) you *must* use the following docker flags. 165 166 | Flag | Description | 167 | --- | --- | 168 | `-rt.dockerRepoDomain` | Artifactory Docker registry domain. | 169 | `-rt.dockerTargetRepo` | Artifactory Docker repository name. | 170 171 ##### Examples 172 To run docker tests execute the following command (fill out the missing parameters as described below). 173 ```` 174 go test -v github.com/jfrog/jfrog-cli-go -test.docker -rt.dockerRepoDomain=DOCKER_DOMAIN -rt.dockerTargetRepo=DOCKER_TARGET_REPO [flags] 175 ```` 176 177 #### Go commands tests 178 ##### Examples 179 To run go tests run the following command. 180 ```` 181 go test -v github.com/jfrog/jfrog-cli-go -test.go [flags] 182 ```` 183 184 #### NuGet tests 185 ##### Requirement 186 * Add NuGet executable to the system search path (PATH environment variable). 187 * Create a remote repository named jfrog-cli-tests-nuget-remote-repo. 188 * Run the following command. 189 190 ##### Examples 191 ```` 192 go test -v github.com/jfrog/jfrog-cli-go -test.nuget [flags] 193 ```` 194 195 #### Pip tests 196 ##### Requirement 197 * Add Python and pip executables to the system search path (PATH environment variable). 198 * Pip tests must run inside a clean pip-environment. You can either activate a virtual-environment and execute the tests from within, or provide the path to your virtual-environment using the -rt.pipVirtualEnv flag. 199 * Run the following command: 200 201 In addition to [general optional flags](#Usage) you can use the following optional pip flags 202 203 | Flag | Description | 204 | --- | --- | 205 | `-rt.pipVirtualEnv` | [Optional] Path to the directory of a clean pip virtual-environment. Make sure to provide the binaries directory (in unix: */bin*, in windows: *\Scripts*). | 206 207 ##### Examples 208 ```` 209 go test -v github.com/jfrog/jfrog-cli-go -test.pip [flags] 210 ```` 211 212 ### Bintray tests 213 Bintray tests credentials are taken from the CLI configuration. If non configured or not passed as flags, the tests will fail. 214 215 To run Bintray tests execute the following command: 216 ```` 217 go test -v github.com/jfrog/jfrog-cli-go -test.bintray 218 ```` 219 Flags: 220 221 | Flag | Description | 222 | --- | --- | 223 | `-bt.user` | [Mandatory if not configured] Bintray username. | 224 | `-bt.key` | [Mandatory if not configured] Bintray API key. | 225 | `-bt.org` | [Optional] Bintray organization. If not configured, *-bt.user* is used as the organization name. | 226 227 * Running the tests will create a repository `jfrog-cli-tests-repo1` in bintray.<br/> 228 Once the tests are completed, the repository will be deleted. 229 230 ### Distribution tests 231 In addition to [general optional flags](#Usage) you *must* use the following flag: 232 233 | Flag | Description | 234 | --- | --- | 235 | `-rt.distUrl` | JFrog Distribution URL. | 236 237 To run distribution tests run the following command: 238 ``` 239 go test -v github.com/jfrog/jfrog-cli-go -test.distribution [flags] 240 ``` 241 242 # Code Contributions 243 We welcome code contributions through pull requests from the community. 244 ## Pull Requests Guidelines 245 * Before creating your first pull request, please join our contributors community by signing [JFrog's CLA](https://secure.echosign.com/public/hostedForm?formid=5IYKLZ2RXB543N). 246 * If the existing tests do not already cover your changes, please add tests.. 247 * Pull requests should be created on the *dev* branch. 248 * Please use [gofmt](https://golang.org/cmd/gofmt/) for formatting the code before submitting the pull request. 249 250 # Using JFrog CLI 251 JFrog CLI can be used for a variety of functions with Artifactory, Bintray, Xray and Mission Control, 252 and has a dedicated set of commands for each product. 253 To learn how to use JFrog CLI, please visit the [JFrog CLI User Guide](https://www.jfrog.com/confluence/display/CLI/Welcome+to+JFrog+CLI). 254 255 ## Using JFrog CLI Docker Image 256 The docker image of JFrog CLI can be pulled from Bintray by running the following command: 257 ```` 258 docker pull docker.bintray.io/jfrog/jfrog-cli-go:latest 259 ```` 260 Run a JFrog CLI command using docker as follows: 261 ```` 262 docker run docker.bintray.io/jfrog/jfrog-cli-go:latest jfrog <COMMAND> 263 ```` 264 265 # Release Notes 266 The release are available on [Bintray](https://bintray.com/jfrog/jfrog-cli-go/jfrog-cli-linux-amd64#release).