Golden Command Line Client

The Golden Client is a command-line tool designed to interact with the Golden API. It can be used in scripts to automate Golden API testing or to streamline interactions with the API. While the client is written in Java, it is primarily intended to be used from the command line. However, it can also be integrated into Java projects if needed.

We provide an open-source project for the Golden Client

The source code is available in a public GitHub repository: https://github.com/trazadera-public/trazadera-golden-cli .

Installation

Clone the github repository.

BASH

git clone https://github.com/trazadera-public/trazadera-golden-cli.git

Compile and package the project using Maven. This will create a Uber JAR (or Fat JAR), that is a single JAR file that contains all the compiled Java classes from the project, and all compiled Java classes from all dependencies.

BASH

mvn clean package

If you are using Unix you can leverage the provided bin/goldencli script that wraps the call to the generated uber jar. Update your .profile to include the script in the path, including something similar to this:

CODE

export GOLDEN_CLI_HOME=/path/to/your/repository/trazadera-golden-cli
export PATH=$PATH:${GOLDEN_CLI_HOME}/bin

Remember to source the profile after the update.

CODE

. $HOME/.profile

If not using Unix, you will have to invoke the Java Uber JAR directly using following command.

Remember to adjust the version of the Uber JAR

CODE

java -jar /path/to/your/repository/trazadera-golden-cli/target/trazadera-golden-cli-1.0.0-jar-with-dependencies.jar

Check that everything works by running the following command.

For the rest of this documentation we will assume that the goldencli command works. If you are using other system than Unix, replace goldencli with the actual call to the Uber JAR

CODE

goldencli --version

You should see as an output the Golden Client version.

CODE

Golden Client version 1.0.0

Authenticating the Client

You need at least the URL and a valid token to authenticate and access the Golden API.

Your administrator or Trazadera Support will provide you with the URL and token to access the Golden API

You have different ways of providing this information to the Golden Client:

Command-line Parameter

Command-line parameter is the least secure method, as process listing might show your credentials

Using this method, you have to indicate the parameters --url and --token for every request.

CODE

goldencli entity list --url https://acme.trazadera.net --token golden:xxxx

Environment Variable

Include this commands in your .profile to keep the information between sessions

Declare the following environment variables before calling goldencli.

CODE

export GOLDEN_TOKEN="golden:xxxx"
export GOLDEN_URL="https://acme.trazadera.net"

Home file

Using this method, you create a file named .golden in your home directory.

Always set the file permissions to the lowest required

Create the file using your preferred method and configure the properties.

CODE

GOLDEN=$HOME/.golden
touch $GOLDEN
echo GOLDEN_TOKEN="golden:xxxx" >$GOLDEN
echo GOLDEN_URL="https://acme.trazadera.net" >>$GOLDEN
chmod 600 $GOLDEN

The Golden Client will read this file every time it is executed.

Using the Client

The Golden Client offers extensive functionality for executing commands and subcommands. Each command typically maps to a module in the Golden API (e.g., entities), while a subcommand represents an action to be performed within that module.

The Golden Client uses double-dash parameters exclusively, following the Unix-style long options convention.

You can always display contextual help by running goldencli --help.

CODE

$ goldencli --help
Golden Client - a command line interface for Golden API

Usage: golden [command] [subcommand] [options] [global-options]

Commands:

   golden                                          Manage golden records
   entity                                          Manage entities
   table                                           Manage tables
   resource                                        Manage resources
   user                                            Manage users
   token                                           Manage tokens
   task                                            Manage tasks

Global Options:
   --help                                          Show help and exit. Optional.
   --version                                       Show version and exit. Optional.
   --token <token>                                 Golden API token to authenticate. Optional.
   --url <url>                                     Golden API URL. Optional.
   --format <format>                               Output format: json (default), table, csv. Optional.
   --filter <expression>                           Output filter: a JSON path expression (https://github.com/json-path/JsonPath)
                                                   to select what to print. Optional.
   --interactive                                   Interactive mode (ignores all other options and enters a prompt). Optional.

Use 'golden [command] --help' for more information about a command.
Use 'golden [command] [subcommand] --help' for more information about a subcommand.

Use command --help or command subcommand --help to show more specific help.

CODE

$ goldencli entity show --help
Golden Client - a command line interface for Golden API
Usage: golden entity show [options] [global-options]

entity show - Show entity

Options:
   --entity <id>                                   Entity ID. Required.

Global Options:
   --help                                          Show help and exit. Optional.
   --version                                       Show version and exit. Optional.
   --token <token>                                 Golden API token to authenticate. Optional.
   --url <url>                                     Golden API URL. Optional.
   --format <format>                               Output format: json (default), table, csv. Optional.
   --filter <expression>                           Output filter: a JSON path expression (https://github.com/json-path/JsonPath)
                                                   to select what to print. Optional.
   --interactive                                   Interactive mode (ignores all other options and enters a prompt). Optional.

Use 'golden [command] --help' for more information about a command.
Use 'golden [command] [subcommand] --help' for more information about a subcommand.

Formatting the Client output

The Golden Client supports multiple output formats. By default, it executes a command and prints the result from the Golden API in JSON format to the standard output, including the full payload.

You can change the output format by using the --format parameter. The following formats are supported:

json (default): The default output format. All interactions with the Golden API are conducted using JSON, including both the request and the response. If you select a different output format, the client will transform the response accordingly.
table: Displays the output as an ASCII table for better readability in a terminal.
csv: Outputs the result in CSV format, suitable for further processing or integration with other tools.

The Golden Client also supports filtering before displaying the output. You can use the filter parameter to apply a JSONPath expression (see https://github.com/json-path/JsonPath ) to select specific parts of the response to print. Since the Golden API returns extensive data, applying filters helps narrow down the output to show only the relevant information.

Let’s look at a command that lists the available tables. The output is unformatted and unfiltered, displaying the complete JSON response from the Golden API.

BASH

$ goldencli table list 
[
  {
    "tables": [
      {
        "id": "holulu-master-client",
        "description": "Holulu Client",
        "dataset": "dataset-holulu-master",
        "history": true,
        "audit": true,
        "created": "2024-02-27T11:44:11.835348Z",
        "size": 250764.0,
        "type": "TABLE",
        "dependency": {
          "uses": [
            "resource:dataset-holulu-master"
          ],
          "usesCount": 1.0,
          "usedBy": [
            "entity:holulu-master"
          ],
          "usedByCount": 1.0
        },
        "locked": false
      },
      {
        "id": "demo-patient",
        "description": "Demo patient",
        "dataset": "dataset-demo-patient",
        "history": true,
        "audit": true,
        "created": "2024-04-09T09:19:18.737333Z",
        "size": 4948.0,
        "type": "TABLE",
        "dependency": {
          "uses": [
            "resource:dataset-demo-patient"
          ],
          "usesCount": 1.0,
          "usedBy": [
            "entity:demo-patient"
          ],
          "usedByCount": 1.0
        },
        "locked": false
      }
    ]
  }
]

Now, let’s explore how to apply formatting and filtering based on the previous output. Using JSONPath, the expression .id selects the id attribute at the root level. We will use this expression to display only the table identifiers instead of the entire content.

BASH

$ goldencli table list --format table --filter .id
╔══════════════════════╗
║ id                   ║
╠══════════════════════╣
║ holulu-master-client ║
╟──────────────────────╢
║ demo-patient         ║
╚══════════════════════╝

$ goldencli table list --format json --filter .id
[
  {
    "id": "holulu-master-client"
  },
  {
    "id": "demo-patient"
  }
]

$ goldencli table list --format csv --filter .id
id
holulu-master-client
demo-patient