gcf-tool

CLI tool to deploy Genesys Cloud Functions - create, update, delete drafts and publish function actions.

Package: @wgroovy/gcf-tool on npm

Installation

npm install -g @wgroovy/gcf-tool

Prerequisites

• Node.js 22 or higher
• gc CLI (version >= 148.0.0), installation — required for --extract, --scaffold --extract, --test, and deploy
• npm (required only when using --npmBuild or --npmZip)

Why the gc CLI?

gcf-tool talks to Genesys Cloud through the gc CLI, not by calling platform APIs directly from Node. That is intentional.

The gc CLI is Genesys’s supported command-line tool for automation and CI/CD. Its profile management — storing credentials, selecting orgs, and switching environments with -p / --profile — is mature and maintained by Genesys. gcf-tool reuses those profiles (including the gcCliProfile default in each function’s package.json) instead of building a second login and token layer of its own.

If you already use gc in pipelines or on your workstation, you configure org access once and every gcf-tool command picks up the same profile. Deploy, extract, and test all stay aligned with how the rest of your Genesys automation works.

Configuration

Each function must be in a separate directory with a gcFunction property configured in its package.json:

{
  "name": "my-function",
  "gcFunction": {
    "integrationName": "The name of GC function integration",
    "functionName": "The name of the GC function",
    "gcCliProfile": "The GC CLI profile name",
    "secure": false
  }
}

Usage

gcf-tool [options]

Options

| Flag | Description | |------|-------------| | -p, --gcProfile <name> | GC CLI profile (default: gcCliProfile from package.json) | | -i, --gcIntegration <name> | GC Integration name (default: integrationName from package.json) | | -f, --gcFunction <name> | GC Function name (default: functionName from package.json) | | -s, --secure | Enable Secure Data support (default: false) | | -d, --dir <path> | Function directory (default: .) | | -t, --runtime <n> | Node runtime version (default: 22 → nodejs22.x) | | -a, --apply | Apply changes (dry-run mode without this flag) | | -r, --remove | Delete draft and published action (dry-run without -y) | | -y, --yes | Auto-confirm publish/delete | | -n, --noPublish | Never publish (even with --apply) | | -z, --npmBuild | Run npm run build before uploading src.zip | | --npmZip | Run npm run zip before uploading src.zip (cannot be combined with --npmBuild) | | -b, --bulk <folders> | Comma-separated folders or @file (supports glob *) | | -c, --scaffold | Create package.json with gcFunction config and index.mjs if they don't exist | | -e, --extract | Extract action schemas, request, and response config to local JSON files | | --inputSchema | Only extract the input schema (requires --extract or --scaffold) | | --successSchema | Only extract the success schema (requires --extract or --scaffold) | | --test | Execute a function action test in the Genesys Cloud org (prefers draft, falls back to published) | | --testJson <file\|json> | Test input JSON file or inline JSON string (default: input.json) | | --request | Only extract the request config (requires --extract or --scaffold) | | --response | Only extract the response config (requires --extract or --scaffold) | | -v, --verbose | Verbose logging | | -h, --help | Show help | | --version | Show version |

Examples

# Dry-run mode (simulate changes)
gcf-tool

# Create/update draft and publish
gcf-tool -a -y

# Create/update draft without publishing
gcf-tool -a -n

# Run npm build before uploading
gcf-tool -a -z

# Run npm zip before uploading
gcf-tool -a --npmZip

# Process multiple folders
gcf-tool -a -b "folder1,folder2"

# Process folders from file
gcf-tool -a -b "@folders.txt"

# Delete function (dry-run)
gcf-tool -r

# Delete function (confirm)
gcf-tool -r -y

# Use custom profile/integration/function names
gcf-tool -a -p myprofile -i "My Integration" -f "My Function"

# Extract action schemas and config to current directory
gcf-tool -e

# Extract to a specific directory
gcf-tool -e -d /path/to/dir

# Extract only the input schema
gcf-tool -e --inputSchema

# Extract only request and response configs
gcf-tool -e --request --response

# Extract multiple functions to their respective directories
gcf-tool -e -b "folder1,folder2"

# Extract with custom profile/integration/function
gcf-tool -e -p myprofile -i "My Integration" -f "My Function"

# Scaffold a new function directory (creates package.json + index.mjs)
gcf-tool -c -i "GCF Utilities" -f LookupTagConfig_01 -p centerpoint-westprod

# Scaffold in current directory (uses directory name as functionName)
gcf-tool -c -i "GCF Utilities"

# Scaffold multiple directories at once
gcf-tool -c -i "GCF Utilities" -b "folder1,folder2"

# Scaffold and then extract configs into the new directory
gcf-tool -c -i "GCF Utilities" -e

# Scaffold multiple directories, then extract configs into each
gcf-tool -c -i "GCF Utilities" -e -b "folder1,folder2"

# Test a function action (uses input.json)
gcf-tool --test

# Test with custom input file
gcf-tool --test --testJson test-cases.json

# Test with an inline JSON string instead of a file
gcf-tool --test --testJson '{"datetime":"2026-01-01T00:00:00Z"}'

# Test multiple functions
gcf-tool --test -b "folder1,folder2"

Behavior

• Dry-run by default: No changes are made unless --apply is specified.
• Apply mode (--apply): Creates/updates draft, resolves the function handler from index.js, index.mjs, or index.cjs inside src.zip, uploads src.zip if changed for the active GC CLI profile, waits for deployment, validates, and optionally publishes.
• Profile-aware upload state: src.md5 remembers the last uploaded src.zip hash per GC CLI profile. Reusing the same function directory with a different profile triggers a fresh upload until that profile has its own remembered state.
• Publish:
  • With --yes: publishes automatically
  • Without --yes in interactive TTY: prompts for confirmation
  • Without --yes in non-interactive mode: skips publish for safety
• Extract mode (--extract): Get an action's configuration from the specified org and extract schemas and templates to local JSON files — the inverse of deploy. By default fetches the action to create inputSchema.json, successSchema.json, request.json and response.json. Prefers the published action; falls back to the draft if no published action exists. Use --inputSchema, --successSchema, --request, --response to limit which files are written — if none are specified, all four are written (backward compatible).
• Scaffold mode (--scaffold): Bootstrap a new function directory by creating package.json (with gcFunction config) and index.mjs (with an empty handler). Use -i to specify the integration name (required), -f for function name (defaults to directory name), -p for GC CLI profile (defaults to default), and -s for secure data (defaults to false). If package.json already exists with a gcFunction section, it is skipped. If index.js/index.mjs/index.cjs already exists, index.mjs creation is skipped.
• Scaffold + Extract (combine --scaffold --extract): Scaffold first (creates directory and package.json), then extract the action configs from GC into the same directory. Selective sub-flags control only the extract phase.
• Test mode (--test): Execute a function action test in the Genesys Cloud org. Prefers the draft action; falls back to the published action if no draft exists. Reads test input from input.json by default; override with --testJson, which accepts either a file path or an inline JSON string. A value whose first non-whitespace character is { or [ is treated as inline JSON and piped to the GC CLI over stdin; anything else is treated as a path, resolved against the function directory unless it is already absolute. The input is resolved and parsed before any GC call, so a bad path or malformed JSON fails immediately. In bulk mode an inline payload is sent to every function, and a warning says so. The command and input are logged to console, then pass/fail is reported. Dry-run does not apply — test execution is always read-only. The --flatten=true flag is passed to the GC CLI. In bulk mode, failures are reported per-directory and processing continues. Requires only the gc CLI. Supports --verbose to print the full raw JSON response.

Directory Structure

my-function/
├── index.mjs          # The entry file containing `export async function handler(event, context)`
├── package.json       # Contains gcFunction config
├── src.zip            # Compiled function code (required)
├── src.md5            # Auto-generated upload state keyed by GC CLI profile
├── request.json       # Request configuration (optional)
├── response.json      # Response configuration (optional)
├── inputSchema.json   # Input schema (optional, for never-published functions)
├── successSchema.json # Success schema (optional, for never-published functions)
├── input.json         # Test input (optional, default source for --test)

src.md5 is a sidecar state file managed by gcf-tool. It stores the remembered src.zip hash for each GC CLI profile used with that function directory so same-profile redeploys can skip redundant uploads while profile switches still upload the current artifact to the new org. Older single-hash src.md5 files are treated as legacy state for the currently active profile and are rewritten into the profile-keyed format after the next successful upload.

gcf-tool resolves the function handler based on the directory in the src.zip file. Supported entry file names are index.js, index.mjs, or index.cjs. If the zip file contains src/index.js, the resovled handler is src/index.handler; if it contains a root-level index.mjs, the handler is index.handler. If multiple plausible index.* entries exist at the same precedence level, the command fails instead of guessing.

Schema Examples

inputSchema.json

{
  "type": "object",
  "required": [
    "datetime"
  ],
  "properties": {
    "datetime": {
      "type": "string",
      "description": "local datetime in ISO format, e.g. 2023-01-01T08:00:00",
      "default": "2023-01-01T08:00:00"
    },
    "timezone": {
      "type": "string",
      "description": "timezone name in timezonedb format, e.g. America/New_York",
      "default": "America/New_York"
    }
  }
}

successSchema.json

{
  "type": "object",
  "properties": {
    "datetimeUtc": {
      "type": "string",
      "description": "UTC datetime in ISO format, e.g. 2023-01-01T13:00:00.000Z"
    },
    "error": {
      "type": "string"
    },
    "statusCode": {
      "type": "integer"
    }
  }
}

Template Examples

request.json

{
  "requestType": "POST",
  "requestTemplate": "{}",
  "headers": {
    "x-logger-host": "${credentials.logger_host}",
    "x-logger-token": "${credentials.logger_token}"
  }
}

response.json

{
  "translationMap": {},
  "translationMapDefaults": {},
  "successTemplate": "{}"
}

Documentation

• User Guide — task-oriented walkthrough of the common workflows (deploy, extract, test, scaffold, delete, bulk).

License

MIT