gcf-tool

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

Installation

npm install -g @wgroovy/gcf-tool

Prerequisites

• Node.js 22 or higher
• gc CLI (version >= 148.0.0)
• curl
• md5sum
• unzip

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, --no-publish | Never publish (even with --apply) | | -z, --npm-build | Run npm run build before uploading src.zip | | -b, --bulk <folders> | Comma-separated folders or @file (supports glob *) | | -v, --verbose | Verbose logging | | -h, --help | Show help |

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

# 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"

Behavior

• Dry-run by default: No changes are made unless -a (apply) is specified.
• Apply mode: 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

Directory Structure

my-function/
├── 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)

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 from the contents of src.zip, not from the source directory. Supported entry files are index.js, index.mjs, and index.cjs. If the archive contains src/index.js, the resulting 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

These are the full example contents of the optional schema files.

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"
    }
  }
}

License

MIT