GammaAI DX CLI Plugin

A Salesforce CLI plugin for seamless export and import of GammaAI agent configurations. Built for teams managing AI agent versioning, CI/CD pipelines, and multi-org deployments.

Installation

sf plugins install @bluegamma/gammaai-dx-cli

To install a specific version:

sf plugins install @bluegamma/[email protected]

Requirements

• Salesforce CLI (sf) installed
• Node.js >= 18.0.0
• An authenticated Salesforce org with GammaAI deployed

Commands

• gammaai-dx-cli gammaai export
• gammaai-dx-cli gammaai import

gammaai-dx-cli gammaai export

Connects to a Salesforce org via Apex REST and exports GammaAI agent version configuration data to a local JSON file. The output file is automatically named after the agent version name retrieved from the org.

USAGE
  $ gammaai-dx-cli gammaai export [--json] [--flags-dir <value>] [-o <value>] [-s <value>] [-a <value>] [-f <value>]
    [-l <value>]

FLAGS
  -a, --agent-name=<value>        Filters the export to agent versions matching the specified agent name.
  -f, --output=<value>            [default: ./data] Directory path where the exported JSON file will be saved. The file
                                  is automatically named after the agent version name (e.g., User_Agent_Version_1.json).
                                  Defaults to ./data.
  -l, --log-file=<value>          [default: ./logs/error.log] File path for logging export errors. Defaults to
                                  ./logs/error.log.
  -o, --target-org=<value>        Username or alias of the target Salesforce org to export data from.
  -s, --source-system-id=<value>  Filters the export to a specific agent version using its source system identifier
                                  (UUID).

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

EXAMPLES
  sf gammaai export --target-org MyOrg

  sf gammaai export --target-org MyOrg --source-system-id "ea3fc60f-861b-458f-91a3-feb7edcc4c3c"

  sf gammaai export --target-org MyOrg --agent-name "User Agent"

  sf gammaai export --target-org MyOrg --source-system-id "ea3fc60f-861b-458f-91a3-feb7edcc4c3c" --agent-name "User Agent"

  sf gammaai export --target-org MyOrg --output ./exports --log-file ./logs/export-error.log

gammaai-dx-cli gammaai import

Import an agent configuration JSON file into a Salesforce org using GammaAI deployment.

USAGE
  $ gammaai-dx-cli gammaai import -o <value> -f <value> [--json] [--flags-dir <value>] [-l <value>]

FLAGS
  -f, --input-file=<value>  (required) Path to the agent configuration JSON file to import.
  -l, --log-file=<value>    [default: ./logs/error.log] Path to the log file where errors will be written. Defaults to
                            ./logs/error.log.
  -o, --target-org=<value>  (required) Username or alias of the target Salesforce org to import the agent configuration
                            into.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

EXAMPLES
  sf gammaai import --input-file ./agents/my-agent.json --target-org myOrg

  sf gammaai import --input-file ./agents/my-agent.json --target-org myOrg --log-file ./logs/import.log

  sf gammaai import -f ./agents/my-agent.json -o myOrg -l ./logs/import.log

• sf gammaai export
• sf gammaai import

sf gammaai export

Connects to a Salesforce org via Apex REST and exports GammaAI agent version configuration data to a local JSON file. The output file is automatically named after the agent version name retrieved from the org.

USAGE
  $ sf gammaai export [--json] [--flags-dir <value>] [-o <value>] [-s <value>] [-a <value>] [-f <value>] [-l <value>]

FLAGS
  -o, --target-org=<value>        Username or alias of the target Salesforce org to export data from.
  -s, --source-system-id=<value>  Filters the export to a specific agent version using its source system
                                  identifier (UUID).
  -a, --agent-name=<value>        Filters the export to agent versions matching the specified agent name.
  -f, --output=<value>            [default: ./data] Directory path where the exported JSON file will be
                                  saved. The file is automatically named after the agent version name
                                  (e.g., User_Agent_Version_1.json).
  -l, --log-file=<value>          [default: ./logs/error.log] File path for logging export errors.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

Examples:

# Export all agent data from an org
sf gammaai export --target-org MyOrg

# TODO: Replace YOUR_SOURCE_SYSTEM_ID with a real example UUID for documentation
# Export by source system ID
sf gammaai export --target-org MyOrg --source-system-id "YOUR_SOURCE_SYSTEM_ID"

# Export by agent name
sf gammaai export --target-org MyOrg --agent-name "User Agent"

# TODO: Replace YOUR_SOURCE_SYSTEM_ID with a real example UUID for documentation
# Export with both filters
sf gammaai export --target-org MyOrg --source-system-id "YOUR_SOURCE_SYSTEM_ID" --agent-name "User Agent"

# Export with custom output directory and log file
sf gammaai export --target-org MyOrg --output ./exports --log-file ./logs/export-error.log

sf gammaai import

Imports a GammaAI agent configuration JSON file into a target Salesforce org using the GammaAI Apex REST deployment endpoint.

USAGE
  $ sf gammaai import -o <value> -f <value> [--json] [--flags-dir <value>] [-l <value>]

FLAGS
  -o, --target-org=<value>   (required) Username or alias of the target Salesforce org to import the
                             agent configuration into.
  -f, --input-file=<value>   (required) Path to the agent configuration JSON file to import.
  -l, --log-file=<value>     [default: ./logs/error.log] Path to the log file where errors will be
                             written.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

Examples:

# Import agent configuration into an org
sf gammaai import --input-file ./agents/my-agent.json --target-org myOrg

# Import with a custom log file
sf gammaai import --input-file ./agents/my-agent.json --target-org myOrg --log-file ./logs/import.log

# Import using short flags
sf gammaai import -f ./agents/my-agent.json -o myOrg -l ./logs/import.log

Typical Workflow

Export from a source org and import into a target org:

# Step 1 — Export from source org
# TODO: Replace YOUR_SOURCE_SYSTEM_ID with a real example UUID for documentation
sf gammaai export --target-org SourceOrg --source-system-id "YOUR_SOURCE_SYSTEM_ID"

# Step 2 — Commit exported file to version control (optional)
git add ./data/User_Agent_Version_1.json
git commit -m "chore: export User Agent Version 1 config"

# Step 3 — Import into target org
sf gammaai import --input-file ./data/User_Agent_Version_1.json --target-org TargetOrg

Output Structure

After a successful export, the output directory will contain a JSON file named after the agent version:

./data/
└── User_Agent_Version_1.json

The exported JSON contains the full agent configuration including:

• Agent and agent version details
• Model configuration
• Prompt templates
• Functions and tool inputs
• Action associations
• Authentication configuration
• Audit metadata

Error Handling

All errors are logged to the configured log file (default: ./logs/error.log) in the following format:

[2026-05-07T03:43:12.000Z] ERROR: <error message>
STACK: <stack trace>
--------------------------------------------------

Common errors and fixes:

| Error | Cause | Fix | |---|---|---| | No target org provided | Missing -o flag and no default org set | Add --target-org flag | | Could not find a match for URL | Apex REST class not deployed | Deploy GammaAI package to org | | API returned isSuccess: false | Apex logic returned failure | Check org data and Apex logs | | Could not find agentVersionName | Response missing agent version | Verify source system ID or agent name |

Local Development

Clone and build the plugin locally:

# TODO: Replace YOUR_GITHUB_ORG/YOUR_GITHUB_REPO with actual GitHub repository path
# e.g. git clone https://github.com/bluegamma/gammaai-dx-cli
git clone https://github.com/YOUR_GITHUB_ORG/YOUR_GITHUB_REPO

# Install dependencies and compile
cd gammaai-dx-cli
npm install
npm run build

# Generate oclif manifest
npx oclif manifest

# Link to sf CLI for local testing
sf plugins link .

# Verify plugin is linked
sf plugins

# Run using local dev file
./bin/dev.js gammaai export --target-org MyOrg
./bin/dev.js gammaai import --input-file ./data/User_Agent_Version_1.json --target-org MyOrg

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run linting
npm run lint

Tooling

This plugin is built on the following Salesforce open-source packages:

• @salesforce/core
• @salesforce/sf-plugins-core
• @salesforce/ts-types
• @oclif/core
• @salesforce/dev-scripts

Issues

Please report any issues at https://github.com/YOUR_GITHUB_ORG/YOUR_GITHUB_REPO/issues

Contributing

1. Fork this repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes and write tests
4. Ensure tests pass: npm run test:coverage
5. Ensure linting passes: npm run lint
6. Submit a pull request

Aim for at least 95% code coverage on any new code. Pull requests without unit tests will not be accepted.

License

BSD-3-Clause — see LICENSE for details.