Skip to content

Config Command

Jump to bottom
Raju Gurram edited this page Dec 20, 2025 · 1 revision

Config Command

Overview

The config command manages the Graphman home directory and configuration. It can display the current configuration or initialize a new home directory with default configuration and extension files.

Syntax

graphman config [--init-home <home-directory>]
  [--options.<name> <value>,...]

Parameters

Optional Parameters

Parameter Description Default
--init-home Initialize a new Graphman home directory None (display mode)
--options.encodeSecrets Encode secrets in configuration file false

Behavior

Display Mode (Default)

When run without parameters:

  • Displays the current home directory path
  • Shows the contents of graphman.configuration file
  • Warns if home directory or configuration is not set

Initialize Mode

When --init-home is specified:

  • Creates the specified home directory structure
  • Copies extension modules
  • Creates default configuration file
  • Optionally encodes secrets (passwords, passphrases)
  • Provides instructions for setting GRAPHMAN_HOME environment variable

Home Directory Structure

A Graphman home directory contains:

<home-directory>/
├── graphman.configuration      # Main configuration file
├── modules/                    # Extension modules
│   ├── graphman-extension-pre-request.js
│   ├── graphman-extension-post-export.js
│   ├── graphman-extension-pre-import.js
│   ├── graphman-extension-multiline-text-diff.js
│   └── graphman-extension-policy-code-validator.js
└── queries/                    # Custom queries (optional)
    └── <schema-version>/
        ├── custom-query.json
        └── custom-query.gql

Examples

Display Current Configuration

View current configuration:

graphman config

Sample Output:

info: home /path/to/graphman/home
info: configuration
{
  "gateways": {
    "default": {
      "address": "https://gateway.example.com:8443",
      "username": "admin",
      "password": "encoded:abc123...",
      "rejectUnauthorized": true,
      "allowMutations": false
    }
  },
  "options": {
    "log": "info"
  }
}

Initialize New Home Directory

Create a new Graphman home:

graphman config --init-home /path/to/my-graphman-home

Output:

info: initializing home /path/to/my-graphman-home
info:   creating extension module graphman-extension-pre-request.js
info:   creating extension module graphman-extension-post-export.js
info:   creating extension module graphman-extension-pre-import.js
info:   creating extension module graphman-extension-multiline-text-diff.js
info:   creating extension module graphman-extension-policy-code-validator.js
info:   creating default configuration
info: make sure defining the environment variable, GRAPHMAN_HOME=/path/to/my-graphman-home

Initialize with Secret Encoding

Initialize and encode secrets:

graphman config --init-home /path/to/my-graphman-home --options.encodeSecrets true

This will:

  1. Create the home directory
  2. Create default configuration
  3. Encode any passwords and passphrases in the configuration

Configuration File

Default Configuration Structure

{
  "gateways": {
    "default": {
      "address": "https://localhost:8443",
      "username": "admin",
      "password": "password",
      "rejectUnauthorized": true,
      "allowMutations": false
    }
  },
  "options": {
    "log": "info",
    "schema": "v11.2.0"
  }
}

Gateway Configuration

Each gateway profile contains:

Field Description Required
address Gateway URL (https://host:port) Yes
username Admin username Yes
password Admin password (can be encoded) Yes
rejectUnauthorized Validate SSL certificates No (default: true)
allowMutations Allow import operations No (default: false)
passphrase Key passphrase (if needed) No
keyPath Path to client key No
certPath Path to client certificate No

Global Options

Option Description Default
log Log level (error, warn, info, fine) info
schema Default schema version Latest version
extensions Custom extension paths None

Use Cases

1. Initial Setup

Set up Graphman for first use:

# Initialize home directory
graphman config --init-home ~/graphman-home

# Set environment variable
export GRAPHMAN_HOME=~/graphman-home

# Edit configuration
vim ~/graphman-home/graphman.configuration

# Verify setup
graphman config

2. Multiple Environments

Create separate configurations for different environments:

# Development environment
graphman config --init-home ~/graphman-dev
export GRAPHMAN_HOME=~/graphman-dev
# Edit config for dev gateways

# Production environment
graphman config --init-home ~/graphman-prod
export GRAPHMAN_HOME=~/graphman-prod
# Edit config for prod gateways

3. Team Setup

Initialize home directory for team members:

# Create shared home directory
graphman config --init-home /shared/graphman-home

# Team members set environment variable
export GRAPHMAN_HOME=/shared/graphman-home

4. Configuration Review

Review current configuration:

graphman config

5. Secret Encoding

Encode secrets in existing configuration:

# Re-initialize with encoding
graphman config --init-home ~/graphman-home --options.encodeSecrets true

6. Troubleshooting Setup

Verify Graphman setup:

# Check configuration
graphman config

# Check version
graphman version

# Test gateway connectivity
graphman export --gateway default --using all:summary --output test.json

Environment Variable

Setting GRAPHMAN_HOME

The GRAPHMAN_HOME environment variable tells Graphman where to find its configuration:

Linux/Mac:

# Temporary (current session)
export GRAPHMAN_HOME=/path/to/graphman-home

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export GRAPHMAN_HOME=/path/to/graphman-home' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell):

# Temporary (current session)
$env:GRAPHMAN_HOME = "C:\path\to\graphman-home"

# Permanent (system-wide)
[System.Environment]::SetEnvironmentVariable('GRAPHMAN_HOME', 'C:\path\to\graphman-home', 'User')

Windows (Command Prompt):

# Temporary (current session)
set GRAPHMAN_HOME=C:\path\to\graphman-home

# Permanent (system-wide)
setx GRAPHMAN_HOME "C:\path\to\graphman-home"

Secret Encoding

Password Encoding

Graphman can encode passwords for security:

Encoded Format:

{
  "password": "encoded:base64encodedvalue"
}

Plain Text Format:

{
  "password": "mypassword"
}

Encoding Process

When --options.encodeSecrets true is used:

  1. Reads existing configuration
  2. Identifies password and passphrase fields
  3. Decodes if already encoded (to re-encode)
  4. Encodes using base64
  5. Prefixes with encoded:
  6. Writes back to configuration file

Manual Encoding

To manually encode a password:

echo -n "mypassword" | base64
# Output: bXlwYXNzd29yZA==

# Use in configuration:
"password": "encoded:bXlwYXNzd29yZA=="

Extension Modules

Default Extensions

The following extensions are copied during initialization:

Extension Purpose
pre-request Modify requests before sending to Gateway
post-export Process exported data before saving
pre-import Process data before importing to Gateway
multiline-text-diff Enhanced diff for multiline text
policy-code-validator Validate policy code structure

Custom Extensions

Add custom extensions by:

  1. Creating extension files in modules/ directory
  2. Following the extension naming pattern: graphman-extension-<name>.js
  3. Configuring in graphman.configuration:
{
  "options": {
    "extensions": ["/path/to/custom-extension.js"]
  }
}

Important Notes

  • Installation Directory: Cannot initialize in Graphman installation directory
  • Existing Files: Initialization doesn't overwrite existing files
  • Environment Variable: Must set GRAPHMAN_HOME after initialization
  • Configuration Format: Must be valid JSON
  • Secret Encoding: Optional but recommended for security
  • Multiple Homes: Can have multiple home directories for different purposes
  • Version Control: Consider version controlling configuration (without secrets)

Configuration Best Practices

  1. Use Separate Homes for different environments
  2. Encode Secrets in production configurations
  3. Set allowMutations carefully (false for production)
  4. Use rejectUnauthorized: true in production
  5. Document Gateway Profiles in team documentation
  6. Version Control configuration templates (without secrets)
  7. Backup Configuration before making changes
  8. Use Descriptive Names for gateway profiles

Related Commands

  • version: View Graphman version and home directory
  • export: Use configured gateway profiles
  • import: Use configured gateway profiles

Troubleshooting

Home Directory Not Configured

warn: home directory is not configured
warn: did you forget to configure the GRAPHMAN_HOME environment variable?

Solution:

export GRAPHMAN_HOME=/path/to/graphman-home

Configuration Missing

warn: configuration is missing, /path/to/graphman-home/graphman.configuration

Solution:

graphman config --init-home /path/to/graphman-home

Cannot Initialize Installation Directory

error: installation directory is not modifiable

Solution: Use a different directory outside the Graphman installation.

Invalid Configuration

If configuration is invalid JSON:

# Validate JSON
python -m json.tool ~/graphman-home/graphman.configuration

Workflow Examples

Initial Setup Workflow

#!/bin/bash
# Complete Graphman setup

# Step 1: Initialize home directory
graphman config --init-home ~/graphman-home

# Step 2: Set environment variable
export GRAPHMAN_HOME=~/graphman-home
echo 'export GRAPHMAN_HOME=~/graphman-home' >> ~/.bashrc

# Step 3: Edit configuration
cat > ~/graphman-home/graphman.configuration << 'EOF'
{
  "gateways": {
    "dev": {
      "address": "https://dev-gateway:8443",
      "username": "admin",
      "password": "encoded:ZGV2cGFzc3dvcmQ=",
      "rejectUnauthorized": false,
      "allowMutations": true
    },
    "prod": {
      "address": "https://prod-gateway:8443",
      "username": "admin",
      "password": "encoded:cHJvZHBhc3N3b3Jk",
      "rejectUnauthorized": true,
      "allowMutations": true
    }
  },
  "options": {
    "log": "info",
    "schema": "v11.2.0"
  }
}
EOF

# Step 4: Verify setup
graphman config
graphman version

# Step 5: Test connectivity
graphman export --gateway dev --using all:summary --output test.json

echo "Setup complete!"

Multi-Environment Setup

#!/bin/bash
# Set up multiple environments

# Development
graphman config --init-home ~/graphman-dev
# ... configure for dev ...

# Staging
graphman config --init-home ~/graphman-staging
# ... configure for staging ...

# Production
graphman config --init-home ~/graphman-prod
# ... configure for prod ...

# Create helper scripts
cat > ~/use-dev.sh << 'EOF'
#!/bin/bash
export GRAPHMAN_HOME=~/graphman-dev
echo "Using development environment"
EOF

cat > ~/use-prod.sh << 'EOF'
#!/bin/bash
export GRAPHMAN_HOME=~/graphman-prod
echo "Using production environment"
EOF

chmod +x ~/use-dev.sh ~/use-prod.sh

Contents

Clone this wiki locally