Golden Command Line Client

Introduction

The Golden Command Line Client is a powerful CLI tool for interacting with the Golden API. It enables automation, scripting, and quick data operations directly from the terminal.

Source Code: trazadera-golden-cli on GitHub

Use Cases:

Automate data synchronization workflows
Script deduplication processes
Export data for analysis
Integrate with CI/CD pipelines
Quick ad-hoc queries and operations

Installation

Prerequisites

Java 11 or higher
Maven 3.6+ (for building from source)
Git

Build from Source

BASH

# Clone repository
git clone https://github.com/trazadera-public/trazadera-golden-cli.git
cd trazadera-golden-cli

# Build the project
mvn clean package

This creates an "Uber JAR" containing all dependencies.

Setup PATH (Unix/Linux/macOS)

Add to your ~/.profile or ~/.bashrc:

BASH

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

Apply changes:

BASH

source ~/.profile

Setup PATH (Windows)

Add the bin directory to your system PATH, or create a batch file:

BATCH

@echo off
java -jar C:\path\to\trazadera-golden-cli\target\trazadera-golden-cli-1.0.0-jar-with-dependencies.jar %*

Verify Installation

BASH

goldencli --version

Output:

CODE

Golden Client version 1.0.0

Authentication

The CLI needs your Golden API URL and access token. Choose one of these methods:

Method 1: Environment Variables (Recommended)

Add to your ~/.profile:

BASH

export GOLDEN_URL="https://golden.yourcompany.com"
export GOLDEN_TOKEN="golden:YourAccessToken"

Method 2: Configuration File

Create ~/.golden with restricted permissions:

BASH

touch ~/.golden
echo 'GOLDEN_URL=https://golden.yourcompany.com' > ~/.golden
echo 'GOLDEN_TOKEN=golden:YourAccessToken' >> ~/.golden
chmod 600 ~/.golden

Method 3: Command-Line Parameters

BASH

goldencli entity list --url https://golden.yourcompany.com --token golden:YourAccessToken

Note: Command-line tokens may be visible in process listings. Use for testing only.

Verify Authentication

BASH

goldencli security whoami

Output:

JSON

{
  "token": "golden:***",
  "id": "t-abc123",
  "role": "STEWARD",
  "name": "API Integration",
  "type": "ACCESS_TOKEN"
}

Command Structure

CODE

goldencli [command] [subcommand] [options] [global-options]

Available Commands

Command	Description
`golden`	Manage golden records (search, upsert, buckets)
`entity`	Manage entities
`table`	Manage tables
`resource`	Manage resources
`user`	Manage users
`token`	Manage access tokens
`task`	Manage background tasks
`security`	Security operations

Global Options

Option	Description
`--help`	Show help
`--version`	Show version
`--url <url>`	Golden API URL
`--token <token>`	Access token
`--format <format>`	Output format: `json`, `table`, `csv`
`--filter <expression>`	JSONPath filter expression
`--interactive`	Enter interactive mode

Getting Help

BASH

# General help
goldencli --help

# Command help
goldencli entity --help

# Subcommand help
goldencli entity show --help

Entity Operations

List Entities

BASH

goldencli entity list

With table format:

BASH

goldencli entity list --format table --filter ".id,.status,.records"

Output:

CODE

╔═══════════════╦═══════════╦═════════╗
║ id            ║ status    ║ records ║
╠═══════════════╬═══════════╬═════════╣
║ customers     ║ COMPLETED ║ 15000   ║
╟───────────────╫───────────╫─────────╢
║ products      ║ COMPLETED ║ 5000    ║
╚═══════════════╩═══════════╩═════════╝

Show Entity Details

BASH

goldencli entity show --entity customers

Get Entity Statistics

BASH

goldencli entity statistics --entity customers

Trigger Entity Operations

BASH

# Reindex entity
goldencli entity index --entity customers

# Run classification
goldencli entity classify --entity customers

# Run steward process
goldencli entity steward --entity customers

Golden Record Operations

Search Records

Simple search:

BASH

goldencli golden search --entity customers --query "[email protected]"

Search with limit:

BASH

goldencli golden search --entity customers --query "john" --limit 20

Field-specific search:

BASH

goldencli golden search --entity customers --query "email:[email protected]"

Formatted output:

BASH

goldencli golden search --entity customers --query "john" \
  --format table \
  --filter ".id,.data.email,.data.full_name"

Get Single Record

BASH

goldencli golden record --entity customers --id rec-001

Expanded view with metadata:

BASH

goldencli golden record --entity customers --id rec-001 --expanded

Upsert Records

From JSON file:

BASH

goldencli golden upsert --entity customers --file customers.json

JSON file format:

JSON

[
  {
    "id": "crm-001",
    "email": "[email protected]",
    "full_name": "John Smith"
  },
  {
    "id": "crm-002",
    "email": "[email protected]",
    "full_name": "Jane Doe"
  }
]

Delete Record

BASH

goldencli golden delete --entity customers --id rec-001

Bucket Operations

List Buckets

All buckets:

BASH

goldencli golden buckets --entity customers

Buckets needing review:

BASH

goldencli golden buckets --entity customers --classification REVIEW

Duplicate buckets:

BASH

goldencli golden buckets --entity customers --classification DUPLICATE

Show Bucket Details

BASH

goldencli golden bucket --entity customers --id bucket-001

Merge Bucket

BASH

goldencli golden merge --entity customers --bucket bucket-001

Disconnect Records

BASH

goldencli golden disconnect --entity customers --bucket bucket-001 --records rec-002,rec-003

Table Operations

List Tables

BASH

goldencli table list

With filtering:

BASH

goldencli table list --format table --filter ".id,.size,.records"

Show Table Details

BASH

goldencli table show --table customers

Query Table

BASH

goldencli table query --table customers --filter "email LIKE '%@example.com'" --limit 100

Export Table

Export to CSV:

BASH

goldencli table export --table customers --format CSV --output customers.csv

Export with filter:

BASH

goldencli table export --table customers \
  --format CSV \
  --filter "created_at > '2024-01-01'" \
  --output recent_customers.csv

Export to JSON:

BASH

goldencli table export --table customers --format JSON --output customers.json

Import Data

BASH

goldencli table import --table customers --file new_customers.csv --format CSV

Truncate Table

BASH

goldencli table truncate --table customers

Task Management

List Tasks

All tasks:

BASH

goldencli task list

Running tasks:

BASH

goldencli task list --status RUNNING

Completed tasks:

BASH

goldencli task list --status COMPLETED --limit 10

Show Task Details

BASH

goldencli task show --id task-001

Cancel Task

BASH

goldencli task cancel --id task-001

Monitor Task Progress

BASH

# Simple polling script
while goldencli task show --id task-001 | grep -q '"status": "RUNNING"'; do
  echo "Task still running..."
  sleep 10
done
echo "Task completed!"

Resource Management

List Resources

BASH

goldencli resource list

Filter by type:

BASH

goldencli resource list --type dataset
goldencli resource list --type source
goldencli resource list --type sink

Show Resource Details

BASH

goldencli resource show --id customer_dataset

Create/Update Resource

BASH

goldencli resource save --file dataset.json

Delete Resource

BASH

goldencli resource delete --id my_resource

Output Formatting

Format Options

Format	Description
`json`	Full JSON output (default)
`table`	ASCII table for readability
`csv`	CSV for data processing

JSONPath Filtering

Use the --filter option with JSONPath expressions to select specific fields.

Select single field:

BASH

goldencli entity list --filter ".id"

Select multiple fields:

BASH

goldencli entity list --filter ".id,.status,.records"

Nested fields:

BASH

goldencli golden search --entity customers --query "john" \
  --filter ".id,.data.email,.data.full_name"

Examples

Table format with selected columns:

BASH

goldencli entity list --format table --filter ".id,.status"

Output:

CODE

╔═══════════════╦═══════════╗
║ id            ║ status    ║
╠═══════════════╬═══════════╣
║ customers     ║ COMPLETED ║
╟───────────────╫───────────╢
║ products      ║ COMPLETED ║
╚═══════════════╩═══════════╝

CSV for spreadsheet import:

BASH

goldencli entity list --format csv --filter ".id,.status,.records" > entities.csv

Output:

CODE

id,status,records
customers,COMPLETED,15000
products,COMPLETED,5000

Scripting Examples

Daily Data Sync

BASH

#!/bin/bash
# daily_sync.sh - Sync customer data from CRM

set -e

LOG_FILE="/var/log/golden/sync_$(date +%Y%m%d).log"

echo "Starting sync at $(date)" >> $LOG_FILE

# Export from source system
mysql -h crm-db -u reader -p$DB_PASS \
  -e "SELECT id, email, name, phone FROM customers WHERE updated > DATE_SUB(NOW(), INTERVAL 1 DAY)" \
  --batch > /tmp/crm_customers.csv

# Convert to JSON
python3 csv_to_json.py /tmp/crm_customers.csv /tmp/crm_customers.json

# Upsert to Golden
goldencli golden upsert --entity customers --file /tmp/crm_customers.json >> $LOG_FILE 2>&1

# Trigger reindex
goldencli entity index --entity customers >> $LOG_FILE 2>&1

# Wait for completion
TASK_ID=$(goldencli task list --status RUNNING --format json | jq -r '.[0].id')
while [ "$TASK_ID" != "null" ]; do
  sleep 30
  TASK_ID=$(goldencli task list --status RUNNING --format json | jq -r '.[0].id')
done

echo "Sync completed at $(date)" >> $LOG_FILE

Export and Analyze Duplicates

BASH

#!/bin/bash
# export_duplicates.sh - Export duplicate buckets for analysis

ENTITY=$1
OUTPUT_DIR="/data/exports/$(date +%Y%m%d)"

mkdir -p $OUTPUT_DIR

# Get duplicate bucket count
DUPE_COUNT=$(goldencli entity show --entity $ENTITY \
  --format json | jq '.duplicateBuckets')

echo "Found $DUPE_COUNT duplicate buckets"

# Export bucket list
goldencli golden buckets --entity $ENTITY --classification DUPLICATE \
  --format csv > $OUTPUT_DIR/duplicate_buckets.csv

# Export bucket details
for BUCKET_ID in $(goldencli golden buckets --entity $ENTITY --classification DUPLICATE \
  --format json | jq -r '.[].id'); do
  goldencli golden bucket --entity $ENTITY --id $BUCKET_ID \
    --format json > $OUTPUT_DIR/bucket_${BUCKET_ID}.json
done

echo "Export complete: $OUTPUT_DIR"

Automated Merge Workflow

BASH

#!/bin/bash
# auto_merge.sh - Auto-merge high-confidence duplicates

ENTITY=$1
CONFIDENCE_THRESHOLD=0.95

echo "Processing high-confidence duplicates for $ENTITY"

# Get duplicate buckets
goldencli golden buckets --entity $ENTITY --classification DUPLICATE \
  --format json | jq -c '.[]' | while read BUCKET; do
  
  BUCKET_ID=$(echo $BUCKET | jq -r '.id')
  CONFIDENCE=$(echo $BUCKET | jq -r '.confidence')
  
  # Check if confidence exceeds threshold
  if (( $(echo "$CONFIDENCE > $CONFIDENCE_THRESHOLD" | bc -l) )); then
    echo "Merging bucket $BUCKET_ID (confidence: $CONFIDENCE)"
    goldencli golden merge --entity $ENTITY --bucket $BUCKET_ID
  else
    echo "Skipping bucket $BUCKET_ID (confidence: $CONFIDENCE)"
  fi
done

echo "Auto-merge complete"

Health Check Script

BASH

#!/bin/bash
# health_check.sh - Check Golden API health

set -e

# Check authentication
AUTH=$(goldencli security whoami --format json 2>&1)
if echo "$AUTH" | grep -q '"type": "NONE"'; then
  echo "ERROR: Authentication failed"
  exit 1
fi
echo "Authentication: OK"

# Check entities
ENTITIES=$(goldencli entity list --format json | jq 'length')
echo "Entities available: $ENTITIES"

# Check for running tasks
RUNNING=$(goldencli task list --status RUNNING --format json | jq 'length')
echo "Running tasks: $RUNNING"

# Check for failed tasks (last 24h)
FAILED=$(goldencli task list --status FAILED --limit 100 --format json | \
  jq '[.[] | select(.completed > (now - 86400))] | length')
echo "Failed tasks (24h): $FAILED"

if [ "$FAILED" -gt 0 ]; then
  echo "WARNING: There are failed tasks in the last 24 hours"
  exit 2
fi

echo "Health check: PASSED"

Batch Deduplication Report

BASH

#!/bin/bash
# dedup_report.sh - Generate deduplication status report

echo "=== Deduplication Status Report ==="
echo "Generated: $(date)"
echo ""

for ENTITY in $(goldencli entity list --format json | jq -r '.[].id'); do
  echo "--- Entity: $ENTITY ---"
  
  STATS=$(goldencli entity show --entity $ENTITY --format json)
  
  TOTAL=$(echo $STATS | jq '.records')
  BUCKETS=$(echo $STATS | jq '.buckets')
  DUPES=$(echo $STATS | jq '.duplicateBuckets')
  REVIEW=$(echo $STATS | jq '.reviewBuckets')
  
  echo "  Total records: $TOTAL"
  echo "  Total buckets: $BUCKETS"
  echo "  Duplicate buckets: $DUPES"
  echo "  Review buckets: $REVIEW"
  
  if [ "$TOTAL" -gt 0 ]; then
    DUPE_RATE=$(echo "scale=2; $DUPES * 100 / $BUCKETS" | bc)
    echo "  Duplication rate: ${DUPE_RATE}%"
  fi
  echo ""
done

Interactive Mode

Start an interactive session:

BASH

goldencli --interactive

In interactive mode:

Commands execute without the goldencli prefix
Tab completion available
Command history preserved
Faster execution (no JVM startup per command)

Example session:

CODE

golden> entity list
[{"id": "customers", ...}]

golden> golden search --entity customers --query "john"
[{"id": "rec-001", ...}]

golden> exit

Troubleshooting

Command Not Found

Problem: goldencli: command not found

Solution: Check PATH configuration:

BASH

echo $PATH
which goldencli

Java Not Found

Problem: java: command not found

Solution: Install Java 11+ and set JAVA_HOME:

BASH

export JAVA_HOME=/path/to/java
export PATH=$PATH:$JAVA_HOME/bin

Authentication Failed

Problem: 401 Unauthorized

Solution:

Check token format includes golden: prefix
Verify environment variables are set
Test with explicit parameters:

BASH

goldencli security whoami --url https://... --token golden:...

Connection Timeout

Problem: Connection timed out

Solution:

Verify URL is correct
Check network connectivity
Verify HTTPS is used (not HTTP)

Permission Denied

Problem: 403 Forbidden

Solution: Your token role may not have required permissions. Contact your administrator.

Additional Resources

GitHub Repository - Source code
Golden API - API reference
Developer Guide - Integration guide
JSONPath Documentation - Filter expression syntax