Using the command line tool (graalctl)
Graal Platform provides a command line tool for communicating with our APIs. This tool is named graalctl.
This overview covers graalctl syntax, describes the command operations, and provides common examples. For details about each command, including all the supported flags and subcommands, see the graalctl reference documentation.
Installing graalctl
graalctl is installable on a variety of Linux platforms, macOS and Windows. Find your preferred operating system below.
Install graalctl on Windows
Download the latest release
Or if you have curl installed, use this command:
curl https://github.com/graalsystems/graalctl/releases/latest/download/graalctl-windows-x86_64.exe -o graalctl.exe
Validate the binary (optional)
Download the graalctl file:
curl https://github.com/graalsystems/graalctl/releases/latest/download/graalctl-windows-x86_64.exe.sha256 -o graalctl.exe.sha256"
Validate the graalctl binary against the checksum file:
Using Command Prompt to manually compare CertUtil's output to the checksum file downloaded:
CertUtil -hashfile graalctl.exe SHA256 type graalctl.exe.sha256
Using PowerShell to automate the verification using the
-eq
operator to get aTrue
orFalse
result:$($(CertUtil -hashfile .\graalctl.exe SHA256)[1] -replace " ", "") -eq $(type .\graalctl.exe.sha256)
Append or prepend the graalctl binary folder to your PATH environment variable.
Test your cli:
graalctl version
Install graalctl on Linux
Download the latest release
Or if you have curl installed, use this command:
curl https://github.com/graalsystems/graalctl/releases/latest/download/graalctl-linux-x86_64 -o graalctl
Validate the binary (optional)
Download the graalctl file:
curl https://github.com/graalsystems/graalctl/releases/latest/download/graalctl-linux-x86_64.sha256 -o graalctl.sha256"
Validate the graalctl binary against the checksum file:
echo "$(cat graalctl.sha256) graalctl" | sha256sum --check
Append or prepend the graalctl binary folder to your PATH environment variable.
Test your cli:
graalctl version
Using the CLI
Use the following syntax to run graalctl
commands from your terminal window:
graalctl [command] [flags]
Authentication
You can authenticate your cli against our platform using your credentials or an application.
Example with credentials:
graalctl login --tenant <<my tenant id>> --auth-mode credentials --username <<my username>> --password <<my password>>
Example with application:
graalctl login --tenant <<my tenant id>> --auth-mode application --application-id <<my app id>> --application-secret <<my app secret>>
Private deployments
You can also authenticate your cli for your private deployment of Graal Platform using --url
and --auth-url
options.
graalctl login ... --url https://api.<<my private deployment DNS or API>> --auth-url https://identity.<<my private deployment DNS or API>>
Verbosity and debugging
graalctl verbosity is controlled with the -v or --v flags. The number of flags represents the log level.
Verbosity | Description |
---|---|
-v | A reasonable default log level if you don't want verbosity. |
-vv | Debug level verbosity. |
-vvv | Display HTTP request and response contents and headers without truncation of contents. |
Output options
Use the following sections for information about how you can format or sort the output of certain commands. For details about which commands support the various output options, see the graalctl reference documentation.
The default output format for all graalctl commands is the human readable plain-text format. To output details to your terminal window in a specific format, you can add either the -o or --output flags to a supported graalctl command.
Syntax
Depending on the graalctl operation, the following output formats are supported:
Output format | Description |
---|---|
-o json | Output a JSON formatted API object |
-o jsonquery= | Print the fields defined in a jsonquery expression. |
-o wide | Output in the plain-text format with any additional information |
-o yaml | Output a YAML formatted API object. |
Examples
graalctl version -o jsonquery='.hash'
graalctl version -o json
graalctl version -o yaml
graalctl version -o wide=hash
JSONQuery Support
graalctl supports JSONQuery. graalctl uses JSONQuery expressions to filter on specific fields in the JSON object and format the output. The simplest JSONQuery is the expression .
, which takes the input and produces it unchanged as output.