# 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

```bash
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-post-revise.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:

```bash
graphman config
```

**Sample Output:**

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

### Initialize New Home Directory

Create a new Graphman home:

```bash
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-post-revise.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:

```bash
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

```json
{
  "credentials": {
    "default": {
      "username": "admin",
      "password": "7layer",
      "keyFilename": null,
      "certFilename": null,
      "keyPassphrase": null
    }
  },
  "gateways": {
    "default": {
      "address": "https://localhost:8443/graphman",
      "credential": "default",
      "rejectUnauthorized": true,
      "passphrase": "7layer",
      "allowMutations": false
    }
  },
  "options": {
    "log": "info",
    "schema": null,
    "excludeDeprecatedFields": true,
    "policyCodeFormat": "xml",
    "keyFormat": "p12",
    "caFilename": null,
    "extensions": [
      "pre-request",
      "post-export",
      "pre-import",
      "post-revise"
    ]
  }
}
```

<details>
<summary><strong>Old Format (Deprecated - Click to expand)</strong></summary>

```json
{
  "gateways": {
    "default": {
      "address": "https://localhost:8443/graphman",
      "username": "admin",
      "password": "7layer",
      "rejectUnauthorized": false,
      "keyFilename": null,
      "certFilename": null,
      "passphrase": "7layer",
      "allowMutations": false
    }
  },
  "options": {
    "log": "info",
    "policyCodeFormat": "xml",
    "keyFormat": "p12"
  }
}
```

</details>


### Configuration Field Descriptions

#### Credentials Section

The `credentials` section defines reusable authentication profiles that can be referenced by multiple gateways.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | string | Yes | Admin username for gateway authentication |
| `password` | string | Yes* | Admin password (can be plain text or encoded with `encoded:` prefix) |
| `keyFilename` | string | No | Path to client key file for mTLS authentication (e.g., `.p12` or `.pem` file) |
| `certFilename` | string | No | Path to client certificate file for mTLS authentication (`.pem` file) |
| `keyPassphrase` | string | No | Passphrase to decrypt the client key file if it's encrypted |

*Required unless using mTLS authentication with `keyFilename` and `certFilename`

#### Gateways Section

The `gateways` section defines gateway connection profiles. You can define multiple gateway profiles and reference them using the `--gateway` parameter.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `address` | string | Yes | Gateway base URL (e.g., `https://localhost:8443/graphman`) |
| `credential` | string | Yes | Name of the credential profile to use from the `credentials` section |
| `rejectUnauthorized` | boolean | No | Whether to validate SSL certificates. Set to `false` for self-signed certs. Default: `true` |
| `passphrase` | string | No | Additional passphrase for gateway operations (if required by gateway) |
| `allowMutations` | boolean | No | Whether to allow mutation operations (import, delete). Default: `false` for safety |

#### Options Section

The `options` section defines global configuration settings for the Graphman client.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `log` | string | No | Log level: `error`, `warn`, `info`, or `fine`. Default: `info` |
| `schema` | string | No | GraphQL schema version to use (e.g., `v11.2.0`). Default: latest supported version |
| `excludeDeprecatedFields` | boolean | No | Whether to exclude deprecated fields from queries. Default: `true` |
| `policyCodeFormat` | string | No | Format for policy code: `xml` or `json`. Default: `xml` |
| `keyFormat` | string | No | Format for private keys: `p12` or `pem`. Default: `p12` |
| `caFilename` | string | No | Path to custom CA certificate file for SSL validation |
| `extensions` | array | No | List of extension module names to load (e.g., `["pre-request", "post-export"]`) |

## Use Cases

### 1. Initial Setup

Set up Graphman for first use:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
graphman config
```

### 5. Secret Encoding

Encode secrets in existing configuration:

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

### 6. Troubleshooting Setup

Verify Graphman setup:

```bash
# 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:**

```bash
# 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):**

```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):**

```cmd
# 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:**
```json
{
  "password": "encoded:base64encodedvalue"
}
```

**Plain Text Format:**
```json
{
  "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:

```bash
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`:

```json
{
  "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](Version-Command.md)**: View Graphman version and home directory
- **[export](Export-Command.md)**: Use configured gateway profiles
- **[import](Import-Command.md)**: 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:**
```bash
export GRAPHMAN_HOME=/path/to/graphman-home
```

### Configuration Missing

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

**Solution:**
```bash
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:
```bash
# Validate JSON
python -m json.tool ~/graphman-home/graphman.configuration
```

## Workflow Examples

### Initial Setup Workflow

```bash
#!/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

```bash
#!/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
```