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 the latest version with the following command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/apache/skywalking-cli/master/scripts/install.sh)"
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
Go to the download page to download all available binaries, including macOS, Linux, Windows.
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
.
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
swctl
provides auto-completion support for bash and powershell, which can save you a lot of typing.
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.
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.
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
.
Report events in CD workflows - GitHub Actions
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...
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 |
For developers who want to contribute to this project, see Contribution Guide