Apache SkyWalking CLI

The CLI (Command Line Interface) for 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, same as GUI.

Install

Quick install

Linux

Install the latest version with the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/apache/skywalking-cli/master/scripts/install.sh)"

MacOS

Use Homebrew to install swctl on the macOS.

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.

curl -LO "https://raw.githubusercontent.com/apache/skywalking-cli/master/scripts/install.bat" && .\install.bat

Install by available binaries

Go to the download page 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.

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.

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:

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:

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:

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

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.

# ...

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...

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
> = 0.15.0	> = 11.0.0

Contributing

For developers who want to contribute to this project, see Contribution Guide

License

Apache 2.0 License.