hac-cli

Minimal CLI for SAP Commerce Cloud (Hybris) HAC - FlexibleSearch queries, Groovy scripts, and type introspection

A lightweight, single-binary CLI tool for interacting with SAP Commerce Cloud (Hybris) Administration Console (HAC). Execute FlexibleSearch queries, run Groovy scripts, and introspect your Commerce system—all from the command line.

Features

• FlexibleSearch Queries - Execute queries with dynamic headers, pagination, and raw data extraction via Groovy/JDBC
• Groovy Scripts - Run Groovy scripts with commit control
• Type Introspection - Search and inspect Hybris types, attributes, and inheritance
• Bean Discovery - Browse Spring beans and their methods
• Enum Introspection - List and inspect enum types and values
• Multiple Formats - Output as CSV (default) or JSON with metadata
• Filtering & Pagination - Server-side filtering and pagination support
• Programmatic API - Use as a library in TypeScript/Node.js projects

Installation

npm install -g hac-cli@latest

Quick Start

1. Configure Environments

Create a .env file in your project or ~/.hac-cli/.env:

# Dev Environment
HAC_DEV_URL=https://dev.commerce.example.com/hac/
HAC_DEV_USERNAME=admin
HAC_DEV_PASSWORD=your-password

# QA Environment
HAC_QA_URL=https://qa.commerce.example.com/hac/
HAC_QA_USERNAME=admin
HAC_QA_PASSWORD=your-password

2. Run Your First Query

# List available environments
hac envs

# Execute a FlexibleSearch query (CSV output by default)
hac search "SELECT {pk}, {code}, {name} FROM {Product}" --env dev --limit 10

# Get JSON output
hac search "SELECT {pk} FROM {User}" --env dev --format json

Usage

FlexibleSearch Queries

# Basic query
hac search "SELECT {pk}, {code} FROM {Product}" --env dev

# With pagination
hac search "SELECT * FROM {User}" --env dev --limit 50 --offset 100

# JSON output with metadata
hac search "SELECT {code} FROM {Catalog}" --env dev --format json

CSV Output (default):

# Total: 1250, Returned: 10, Offset: 0, Has_More: true
pk,code,name
8796093054977,product1,Product 1
...

JSON Output:

{
  "metadata": {
    "total": 1250,
    "returned": 10,
    "offset": 0,
    "has_more": true
  },
  "data": [
    { "pk": "8796093054977", "code": "product1", "name": "Product 1" },
    ...
  ]
}

Groovy Scripts

# Read-only script
hac script "return 'hello world'" --env dev

# Script with commit (modifies data)
hac script "product.setName('New Name')" --env dev --commit

Type Introspection

# Search for types containing "product"
hac types product --env dev

# Get detailed info about a specific type
hac types --detail Product --env dev

# Filter attributes (e.g., find catalog-related attributes)
hac types --detail Product --env dev --filter catalog

# Paginate through attributes
hac types --detail Product --env dev --limit 20 --offset 0

Bean Discovery

# List all beans containing "catalog"
hac beans catalog --env dev

# Get methods for a specific bean
hac beans --detail catalogService --env dev

# Filter methods (e.g., find all "get" methods)
hac beans --detail catalogService --env dev --filter get

Enum Introspection

# List all enums containing "status"
hac enums status --env dev

# Get all values for a specific enum
hac enums --detail ArticleApprovalStatus --env dev

MCP Server Usage

Claude Desktop

Add to your Claude Desktop config file with environment variables:

{
  "mcpServers": {
    "hac": {
      "command": "npx",
      "args": ["-p", "hac-cli@latest", "hac-mcp"],
      "env": {
        "HAC_DEV_URL": "https://dev.commerce.example.com/hac/",
        "HAC_DEV_USERNAME": "admin",
        "HAC_DEV_PASSWORD": "your-password"
      }
    }
  }
}

VS Code / Claude Code

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "hac": {
      "command": "npx",
      "args": ["-p", "hac-cli@latest", "hac-mcp"],
      "env": {
        "HAC_DEV_URL": "${input:hac-dev-url}",
        "HAC_DEV_USERNAME": "${input:hac-dev-username}",
        "HAC_DEV_PASSWORD": "${input:hac-dev-password}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "hac-dev-url",
      "description": "HAC DEV Environment URL",
      "password": false
    },
    {
      "type": "promptString",
      "id": "hac-dev-username",
      "description": "HAC DEV Username",
      "password": false
    },
    {
      "type": "promptString",
      "id": "hac-dev-password",
      "description": "HAC DEV Password",
      "password": true
    }
  ]
}

Available MCP Tools:

• hac_search - Execute FlexibleSearch queries
• hac_script_dryrun - Execute Groovy scripts without committing (safe, read-only)
• hac_script_commit - Execute Groovy scripts and commit changes (use with caution!)
• hac_list - List types/beans/enums (with pattern matching)
• hac_get_details - Get detailed info for specific type/bean/enum

Example Tool Calls:

hac_list(env="dev", resource="types", pattern="product")
hac_get_details(env="dev", resource="type", name="Product", filter="catalog")
hac_list(env="dev", resource="beans", pattern="catalog")
hac_get_details(env="dev", resource="bean", name="catalogService")

Programmatic Usage

Use as a library in your TypeScript/Node.js projects:

import { search, types, main } from 'hac-cli'

// Execute a search
const result = await search('dev', 'SELECT {pk} FROM {Product}', 0, 100)
console.log(result.headers)
console.log(result.rows)

// Get type information
const typeInfo = await types('dev', 'Product', '', 0, 50)

// Use the main CLI function
const cliResult = await main(['search', 'SELECT {pk} FROM {Product}', '--env', 'dev'])
if (cliResult.success) {
  console.log(cliResult.data)
}

CLI Reference

Commands

• search "<query>" --env <env> - Execute FlexibleSearch query
• script "<script>" --env <env> - Execute Groovy script
• types [pattern] --env <env> - Search/inspect types
• beans [pattern] --env <env> - Search/inspect beans
• enums [pattern] --env <env> - Search/inspect enums
• envs - List available environments
• help - Show help

Flags

• --env <name> - Environment (required for most commands)
• --detail <name> - Get detailed info about a specific item
• --filter <text> - Filter results (case-insensitive)
• --limit <num> - Max rows to fetch (default: 200 for search, 50 for introspection)
• --offset <num> - Starting offset for pagination (default: 0)
• --format <fmt> - Output format: csv (default), json
• --commit - Commit changes (script only, default: false)
• --verbose - Enable debug logging to stderr

Environment Configuration

The CLI loads configuration from .env files using the following pattern:

HAC_<ENVIRONMENT>_URL=...
HAC_<ENVIRONMENT>_USERNAME=...
HAC_<ENVIRONMENT>_PASSWORD=...

Example for multiple environments:

# Development
HAC_DEV_URL=https://localhost:9002/hac/
HAC_DEV_USERNAME=admin
HAC_DEV_PASSWORD=nimda

# Staging
HAC_STAGING_URL=https://staging.example.com/hac/
HAC_STAGING_USERNAME=admin
HAC_STAGING_PASSWORD=secure-password

Then use with --env dev or --env staging.

How It Works

FlexibleSearch via Groovy

Unlike the HAC web interface, this CLI uses Groovy scripts with direct JDBC access to:

• Extract dynamic column headers from ResultSet metadata
• Support full pagination with offset/limit
• Return raw data without Hybris model overhead
• Handle large result sets efficiently

Authentication

The CLI:

1. Caches CSRF tokens and cookies (30-minute TTL)
2. Reuses authentication across commands
3. Automatically re-authenticates when sessions expire
4. Stores cache in packages/hac-cli/.cache/

Server-Side Operations

All filtering and pagination happens on the Commerce server via Groovy scripts, reducing network overhead and improving performance.

Development

# Install dependencies
bun install

# Run in development mode
bun run dev

# Build for production
bun run build

# Run tests
bun run typecheck && bun run lint

Publishing

# Build and publish to npm
npm publish --access public

License

MIT

Author

Eugen Eistrach - @EugenEistrach

Contributing

Issues and pull requests are welcome!