| Apache SkyWalking CLI |
| =============== |
| |
|  |
|  |
| |
| <img src="https://skywalking.apache.org/assets/logo.svg" alt="Sky Walking logo" height="90px" align="right" /> |
| |
| The CLI (Command Line Interface) for [Apache SkyWalking](https://github.com/apache/skywalking). |
| |
| SkyWalking CLI is a command interaction tool for the SkyWalking user or OPS team, as an alternative besides using |
| browser GUI. It is based on SkyWalking [GraphQL query protocol](https://github.com/apache/skywalking-query-protocol), |
| same as GUI. |
| |
| ## Install |
| |
| ### Quick install |
| |
| #### Linux |
| |
| Install the latest version with the following command: |
| |
| ```shell |
| /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/apache/skywalking-cli/master/scripts/install.sh)" |
| ``` |
| |
| #### MacOS |
| |
| Use [Homebrew](https://brew.sh/) to install swctl on the macOS. |
| |
| ```shell |
| brew update |
| brew install swctl |
| ``` |
| |
| Besides that, you could still use the same command in Linux to install it. |
| |
| #### Windows |
| |
| Note: you need to start cmd or powershell in administrator mode. |
| |
| ```shell |
| curl -LO "https://raw.githubusercontent.com/apache/skywalking-cli/master/scripts/install.bat" && .\install.bat |
| ``` |
| |
| ### Install by available binaries |
| |
| Go to the [download page](https://skywalking.apache.org/downloads/#SkyWalkingCLI) to download all available binaries, |
| including macOS, Linux, Windows. |
| |
| ### Build from source |
| |
| If you want to try the latest features, you can compile the latest source code and build `swctl` by yourself. Since |
| SkyWalking CLI is using `Makefile`, compiling the project is as easy as executing a command in the root directory of the |
| project. |
| |
| ```shell |
| git clone https://github.com/apache/skywalking-cli |
| cd skywalking-cli |
| make |
| ``` |
| |
| Then copy the `./bin/swctl-latest-(darwin|linux|windows)-amd64` to your `PATH` directory according to your OS, |
| usually `/usr/bin/` or `/usr/local/bin`. |
| |
| You can also copy it to any directory you like, then add that directory to `PATH`. **We recommend you to rename |
| the `swctl-latest-(darwin|linux|windows)-amd64` to `swctl`.** |
| |
| ### Run from Docker image |
| |
| If you prefer to use Docker, skywalking-cli also provides Docker images for convenient usages since 0.9.0. We also push |
| the snapshot Docker images to GitHub registry for developers who want to test the latest features, note that this is not |
| Apache releases, and it's for test only, **DO NOT** use it in your production environment. |
| |
| ```shell |
| docker run -it --rm apache/skywalking-cli service ls |
| |
| # Or to use the snapshot Docker image |
| |
| docker run -it --rm ghcr.io/apache/skywalking-cli/skywalking-cli service ls |
| ``` |
| |
| ## Autocompletion |
| |
| `swctl` provides auto-completion support for bash and powershell, which can save you a lot of typing. |
| |
| ### Bash |
| |
| The swctl completion script for bash can be generated with the command `swctl completion bash`. Sourcing the completion |
| script in your shell enables swctl auto-completion: |
| |
| ```shell |
| swctl completion bash > bash_autocomplete && |
| sudo cp ./bash_autocomplete /etc/bash_completion.d/swctl && |
| echo >> ~/.bashrc && |
| echo "export PROG=swctl" >> ~/.bashrc |
| ``` |
| |
| After reloading your shell, swctl auto-completion should be working. |
| |
| ### powershell |
| |
| Similarly, run the following command in your powershell terminal to enable auto-completion: |
| |
| ```shell |
| set-executionpolicy remotesigned -Scope CurrentUser |
| swctl completion powershell >> $profile |
| ``` |
| |
| If you get an error like `OpenError: (:) [Out-File], DirectoryNotFoundException`, then you need to run the following |
| command to create `$profile` file: |
| |
| ```shell |
| New-Item -Type file -Force $profile |
| ``` |
| |
| After reloading your shell, `swctl` auto-completion should be working. |
| |
| ## Help / Manual |
| |
| `swctl` builds the help manual inside the command itself with some useful example commands, please type `swctl help` |
| after installation. If you want to look up detail manual for a specific sub-command, insert `help` before the last |
| sub-command, for example, `swctl service help list` shows the manual for command `swctl service list`, |
| and `swctl install manifest help oap` shows the manual for `swctl install manifest oap`. |
| |
| # More Use Cases |
| |
| <details> |
| <summary>Report events in CD workflows - GitHub Actions</summary> |
| |
| Integrate skywalking-cli into your CD workflows to report events, this is an implementation of GitHub Actions, but we |
| welcome you to contribute plugins of other CD platforms, like Jenkins, GitLab, etc. |
| |
| The usage of integration for GitHub Actions is as follows. |
| |
| ```yaml |
| # ... |
| |
| jobs: |
| deploy: |
| strategy: |
| matrix: |
| instance: |
| - asia-southeast |
| - asia-northeast |
| name: Deploy Product Service |
| runs-on: ubuntu-latest |
| steps: |
| # other steps such as checkout ... |
| |
| - name: Wrap the deployment steps with skywalking-cli |
| uses: apache/skywalking-cli@main # we always suggest using a revision instead of `main` |
| with: |
| oap-url: ${{ secrets.OAP_URL }} # Required. Set the OAP backend URL, such as example.com:11800 |
| auth-token: ${{ secrets.OAP_AUTH_TOKEN }} # Optional. OAP auth token if you enable authentication in OAP |
| service: product # Required. Name of the service to be deployed |
| instance: ${{ matrix.instance }} # Required. Name of the instance to be deployed |
| endpoint: "" # Optional. Endpoint of the service, if any |
| message: "Upgrade from {fromVersion} to {toVersion}" # Optional. The message of the event |
| parameters: "" # Optional. The parameters in the message, if any |
| layer: "GENERAL" # Required. Name of the layer to which the event belongs (case-insensitive) |
| |
| # your package / deployment steps... |
| ``` |
| |
| </details> |
| |
| # Compatibility |
| |
| SkyWalking CLI and SkyWalking OAP communicate with different query versions, here is a summary of the compatible versions of both. |
| Note that many queries in older CLI releases can still work with new OAP versions and vice versa because most query APIs are forward-compatible. |
| The compatibility table here only lists fully compatible OAP versions, which mean new query APIs are implemented in this specific version. |
| |
| | SkyWalking CLI | OAP Server Version | |
| |----------------|---------------| |
| | \> = 0.11.0 | \> = 9.2.0 | |
| | \> = 0.12.0 | \> = 9.3.0 | |
| | \> = 0.12.0 | \> = 9.5.0 | |
| | \> = 0.13.0 | \> = 9.6.0 | |
| | \> = 0.14.0 | \> = 10.2.0 | |
| |
| # Contributing |
| |
| For developers who want to contribute to this project, see [Contribution Guide](CONTRIBUTING.md) |
| |
| # License |
| |
| [Apache 2.0 License.](/LICENSE) |
