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

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

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

   1. Using Command Prompt to manually compare CertUtil's output to the checksum file downloaded:

      CertUtil -hashfile graalctl.exe SHA256
      type graalctl.exe.sha256
      

   2. Using PowerShell to automate the verification using the -eq operator to get a True or False result:

      $($(CertUtil -hashfile .\graalctl.exe SHA256)[1] -replace " ", "") -eq $(type .\graalctl.exe.sha256)
      

3. Append or prepend the graalctl binary folder to your PATH environment variable.

4. Test your cli:

   graalctl version

Install graalctl on Linux

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

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

3. Append or prepend the graalctl binary folder to your PATH environment variable.

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