🚀 vNext Workflow CLI

Cross-platform modern workflow management tool.

A command-line interface (CLI) tool for managing vNext workflows, tasks, schemas, views, functions, extensions, and mappings. This tool helps you synchronize your local workflow definitions with the vNext API and database.

Package: @burgan-tech/vnext-workflow-cli
NPM: https://www.npmjs.com/package/@burgan-tech/vnext-workflow-cli
GitHub: https://github.com/burgan-tech/vnext-workflow-cli

📦 Installation

Install from NPM (Recommended)

# Install globally
npm install -g @burgan-tech/vnext-workflow-cli

# Or install as a project dependency
npm install @burgan-tech/vnext-workflow-cli

After installation, you can use the CLI with any of these aliases:

wf --version       # short alias
vnext --version    # alternative alias (recommended for Windows)
workflow --version # full name

Install from Source

# Clone the repository
git clone https://github.com/burgan-tech/vnext-workflow-cli.git
cd vnext-workflow-cli

# Install dependencies
npm install

# Link globally (for development)
npm link

Requirements

Node.js >= 14.0.0
npm or yarn
PostgreSQL (for database operations)
Docker (optional, for PostgreSQL container)

📄 vnext.config.json (Required)

Every vNext workspace must have at least one solution file in the project root. The default solution file is vnext.config.json; a workspace that hosts several domains adds one vnext.{domain}.config.json per extra domain (see Multiple solutions in one workspace). A solution file defines the domain and component paths.

Example Configuration

{
  "version": "1.0.0",
  "domain": "core",
  "paths": {
    "componentsRoot": "core",
    "tasks": "Tasks",
    "views": "Views",
    "functions": "Functions",
    "extensions": "Extensions",
    "workflows": "Workflows",
    "schemas": "Schemas",
    "mappings": "Mappings"
  }
}

Key Properties

Property	Description
`domain`	Domain name of this solution. Must match a CLI domain profile (`wf domain add <name>`) and the `domain` field of every component under this solution
`paths.componentsRoot`	Root folder where all components are located
`paths.tasks`	Tasks folder name under componentsRoot
`paths.workflows`	Workflows folder name under componentsRoot
`paths.schemas`	Schemas folder name under componentsRoot
`paths.views`	Views folder name under componentsRoot
`paths.functions`	Functions folder name under componentsRoot
`paths.extensions`	Extensions folder name under componentsRoot
`paths.mappings`	Mappings folder name under componentsRoot

Component Discovery

The CLI scans componentsRoot recursively and:

Includes all .json files in subfolders
Ignores .meta folders
Ignores *.diagram.json files
Ignores package*.json and *config*.json files

Multiple solutions in one workspace

A single workspace can hold several domains side by side. Each domain gets its own solution file in the project root and its own componentsRoot:

my-workspace/
├── vnext.config.json            # domain "core"     → componentsRoot "core"
├── vnext.partner.config.json    # domain "partner"  → componentsRoot "partner"
├── core/
│   ├── Workflows/ …
│   └── Tasks/ …
└── partner/
    ├── Workflows/ …
    └── Views/ …

Rules:

File name: vnext.config.json (default) or vnext.{domain}.config.json. The {domain} part is only used to find the file; the domain field inside the file is authoritative. If the two differ, a warning is printed and the field wins.
Separate folders: every solution points at its own paths.componentsRoot. Discovery, --file, --folder and Git-changed detection are all scoped to that folder.
Profiles: each solution's domain is looked up in the CLI domain profiles (wf domain list). A solution with no matching profile is skipped with a warning by check/sync/update/reset (csx needs no profile and always runs).
Component domain check: every component JSON must carry a domain equal to its solution's domain. A missing or different value fails that component with DOMAIN_MISMATCH; the rest of the batch continues.
Sequential processing: with no --domain option, every workspace command runs once per solution, in order, each under its own banner, followed by a WORKSPACE SUMMARY and a combined error table with a Domain column.
--domain <name>: global option that restricts any command to one solution. Works before or after the command name (wf update --domain partner, wf --domain partner update).
Duplicate domains: two solution files declaring the same domain are both rejected.

⚡ Quick Start

Initial Configuration

After installation, navigate to your vNext project and run:

# Go to your vNext project directory
cd /path/to/your/vnext-project

# Database settings (if using Docker)
wf config set USE_DOCKER true
wf config set DOCKER_POSTGRES_CONTAINER vnext-postgres

# Verify configuration
wf check

Note: The CLI automatically uses the current working directory as the project root. Just cd into your project folder before running commands.

Tip: All examples use wf but you can also use vnext or workflow interchangeably. The vnext alias is recommended on Windows where wf may conflict with existing system commands.

Basic Usage

# System status check
wf check

# Update CSX + JSON files (automatically finds changed files)
wf update

# Add missing workflows to database
wf sync

# Reset workflows (delete from DB and re-add)
wf reset

📖 Commands

All workspace commands (check, csx, sync, update, reset) accept the global --domain <name> option. Without it they run once per solution file found in the project root.

`wf check`

Purpose: System health check

For every solution, checks and displays:

Solution file status, domain and components root
API connection status (skipped with a wf domain add hint when the domain has no CLI profile)
Database connection status
Component folders found

wf check                   # every solution in the workspace
wf check --domain partner  # one solution

`wf sync`

Purpose: Add missing components to database (skip existing)

What it does:

Scans all CSX files and updates JSON files with base64 encoded content
For each component JSON file:
- Checks if it exists in DB (by key)
- If exists → Skip (already synced)
- If not exists → Publish to API
Re-initializes the system

Use when: Initial setup, adding new components without affecting existing ones

wf sync

`wf update [options]`

Purpose: Update changed components (delete + re-add)

What it does:

Finds changed CSX files (Git) and updates JSON files
For each component JSON file:
- Checks if it exists in DB (by key)
- If exists → Delete from DB, then publish to API
- If not exists → Publish to API
Re-initializes the system

Use when: You modified existing components and want to update them

wf update                          # Process changed files in Git (CSX + JSON), every solution
wf update --all                    # Update all (asks for confirmation once, for all domains)
wf update --file x.json            # Process a single file (its solution is derived from the path)
wf update --folder person          # Process every component under a feature folder, ignoring Git
wf update --domain partner --all   # Only the "partner" solution

In a multi-solution workspace --file is routed to the solution whose componentsRoot contains the file; combining it with a different --domain is an error. --folder is resolved inside each solution separately (an exact path is only accepted inside that solution's componentsRoot).

--folder <name> (-d): Updates every component belonging to a feature, across all component types, regardless of Git status. It resolves <name> in two ways:

Feature name (e.g. person): matches <name> under every component-type root (Workflows/person, Tasks/person, Views/person, Schemas/person, …) and updates all of them together.
Exact path (e.g. Workflows/person or an absolute path): updates only that specific folder.

If nothing matches, the command lists the feature folder names it did find so you can correct a typo. --file takes precedence over --folder, which takes precedence over --all.

wf update --folder person          # Every "person" folder across all component types
wf update -d Workflows/person      # Only Workflows/person

`wf reset`

Purpose: Force reset components (always delete + re-add)

What it does:

Shows interactive menu to select component type
For each component JSON file:
- Checks if it exists in DB (by key)
- If exists → Delete from DB, then publish to API
- If not exists → Publish to API
Re-initializes the system

Use when: You need to force reset components regardless of changes

wf reset                 # Select folder from interactive menu
wf reset --domain core   # Skip the domain picker in a multi-solution workspace

In a workspace with several solution files, wf reset first asks which domain to reset (unless --domain is given), then shows the folder menu for that solution.

Menu Options:

? Which folder should be reset?
❯ tasks (Tasks/)
  views (Views/)
  functions (Functions/)
  extensions (Extensions/)
  workflows (Workflows/)
  schemas (Schemas/)
  mappings (Mappings/)
  ──────────────
  TUMU (All folders)

`wf csx [options]`

Purpose: Convert CSX files to Base64 and embed in JSON files

What it does:

Finds CSX files (changed or all)
Converts to Base64
Updates ALL JSON files that reference the CSX file
Updates ALL matching location references in each JSON

Use when: You only want to update CSX content in JSONs without publishing to API

wf csx                       # Process changed files in Git, every solution
wf csx --all                 # Process all CSX files
wf csx --file x.csx          # Process a single file
wf csx --domain partner      # Only the "partner" solution

csx does not need a CLI domain profile, so it also runs for solutions whose domain has no profile yet.

`wf config <action> [key] [value]`

Purpose: Configuration management

wf config get              # Show all settings (active domain)
wf config get PROJECT_ROOT # Show a specific setting
wf config set DB_PASSWORD pass # Change a setting (on active domain)

Note: config get and config set always operate on the active domain. Use wf domain use <name> to switch domains.

`wf domain [action] [name] [options]`

Purpose: Multidomain management

Manage multiple domain configurations (API/DB connection profiles). Workspace commands pick the profile whose name equals each solution's domain; wf config get/set operate on the active domain (wf domain use).

# Show active domain name
wf domain active

# List all domains
wf domain list
wf domain --list

# Add a new domain
wf domain add staging --API_BASE_URL http://staging.example.com:4201 --DB_NAME vNext_StagingDb

# Add a domain with multiple settings
wf domain add production \
  --API_BASE_URL http://prod.example.com:4201 \
  --DB_NAME vNext_ProdDb \
  --DB_HOST prod-db.example.com \
  --DB_USER prod_user \
  --DB_PASSWORD prod_pass

# Switch active domain
wf domain use staging

# Remove a domain
wf domain remove staging

Notes:

When adding a domain, any unspecified settings are inherited from the default domain.
The default domain cannot be removed.
If the active domain is removed, the CLI automatically switches to default.

⚙️ Configuration Variables

Config file location: ~/.config/vnext-workflow-cli/config.json

Config File Format

The config file uses a domain-aware structure. Each domain has its own set of configuration values:

{
  "ACTIVE_DOMAIN": "default",
  "DOMAINS": [
    {
      "DOMAIN_NAME": "default",
      "AUTO_DISCOVER": true,
      "API_BASE_URL": "http://localhost:4201",
      "API_VERSION": "v1",
      "DB_HOST": "localhost",
      "DB_PORT": 5432,
      "DB_NAME": "vNext_WorkflowDb",
      "DB_USER": "postgres",
      "DB_PASSWORD": "postgres",
      "USE_DOCKER": false,
      "DOCKER_POSTGRES_CONTAINER": "vnext-postgres",
      "DEBUG_MODE": false
    }
  ]
}

All Available Settings (Per Domain)

Variable	Default	Description
`PROJECT_ROOT`	`process.cwd()`	Auto. Always uses current working directory (cannot be changed)
`AUTO_DISCOVER`	`true`	Enable automatic component folder discovery
`API_BASE_URL`	`http://localhost:4201`	vNext API base URL
`API_VERSION`	`v1`	API version
`DB_HOST`	`localhost`	PostgreSQL host
`DB_PORT`	`5432`	PostgreSQL port
`DB_NAME`	`vNext_WorkflowDb`	PostgreSQL database name
`DB_USER`	`postgres`	PostgreSQL username
`DB_PASSWORD`	`postgres`	PostgreSQL password
`USE_DOCKER`	`false`	Use Docker for PostgreSQL connection
`DOCKER_POSTGRES_CONTAINER`	`vnext-postgres`	Docker container name for PostgreSQL
`DEBUG_MODE`	`false`	Enable debug logging

Note: PROJECT_ROOT is always the current working directory (process.cwd()). Simply cd into your project folder before running any command.

Quick Setup Examples

# API settings (applied to active domain)
wf config set API_BASE_URL http://localhost:4201
wf config set API_VERSION v1

# Database settings (direct connection)
wf config set DB_HOST localhost
wf config set DB_PORT 5432
wf config set DB_NAME vNext_WorkflowDb
wf config set DB_USER postgres
wf config set DB_PASSWORD your_password
wf config set USE_DOCKER false

# Database settings (Docker)
wf config set USE_DOCKER true
wf config set DOCKER_POSTGRES_CONTAINER vnext-postgres

# Other settings
wf config set AUTO_DISCOVER true
wf config set DEBUG_MODE false

💡 Usage Scenarios

1. First Time Setup

# Go to your vNext project
cd /path/to/project

# Check system status
wf check

# Sync all components (add missing ones)
wf sync

2. Daily Development - Changed Files

# Edit CSX or JSON files
vim MyTask.csx

# Update only changed components
wf update

3. Update All Components

# Force update all components
wf update --all

4. Reset Specific Component Type

# Interactive menu
wf reset

5. Only Update CSX in JSONs (No API)

# Update CSX content in JSON files without publishing
wf csx

5b. Update a Whole Feature Folder (No Git Needed)

# Update every "person" component across Workflows/, Tasks/, Views/, Schemas/, ...
wf update --folder person

# Or target one exact folder
wf update --folder Workflows/person

6. Multidomain Workflow

# Add domain profiles (one-time setup)
wf domain add core    --API_BASE_URL http://localhost:4201 --DB_NAME vNext_Core
wf domain add partner --API_BASE_URL http://localhost:4221 --DB_NAME vNext_Partner

# One workspace, two solution files
cd ~/projects/my-workspace   # vnext.config.json ("core") + vnext.partner.config.json ("partner")
wf check                     # both domains, each with its own banner
wf update                    # git-changed files of core, then of partner
wf update --domain partner   # only partner

# Separate workspaces still work exactly as before
cd ~/projects/core-app       # vnext.config.json has "domain": "core"
wf update                    # uses the "core" profile

# See all profiles
wf domain list

🔄 Command Comparison

Command	DB Check	Existing Action	New Action	Use Case
`sync`	Yes	Skip	Publish	Add missing components
`update`	Yes	Delete + Publish	Publish	Update changed components
`update --folder <name>`	Yes	Delete + Publish	Publish	Update every component in a feature folder (ignores Git)
`reset`	Yes	Delete + Publish	Publish	Force reset components
`csx`	No	N/A	N/A	Only update CSX in JSONs

🔀 Multidomain Support

Overview

The CLI supports managing multiple domain configurations. Each domain has its own API_BASE_URL, DB_NAME, and other settings, stored as a domain profile. A workspace may contain one or many solution files, and each solution is processed with the profile that matches its domain.

Solution → Profile Resolution

Before a workspace command runs, the CLI:

Lists the solution files in the current directory: vnext.config.json plus every vnext.{domain}.config.json.
Reads the domain field of each one.
Looks up a CLI domain profile with the same name (DOMAINS[].DOMAIN_NAME).
Runs the command once per solution, sequentially, with that profile's API/DB settings. A solution without a profile is skipped with a hint:
```
⚠ No CLI domain profile for "partner" — skipped.
    Run: wf domain add partner --API_BASE_URL <url> --DB_NAME <db>
```

ACTIVE_DOMAIN is not changed by running commands in a workspace. It only affects wf domain active and wf config get/set. Use --domain <name> to restrict a command to a single solution.

Upgrading from 1.x: earlier versions rewrote ACTIVE_DOMAIN to the workspace's domain on every command ("auto domain resolution"). That side effect is gone; wf config get now always shows the domain you last selected with wf domain use.

Example: two profiles, two solutions in one workspace:

wf domain add core    --DB_NAME vNext_Core
wf domain add partner --DB_NAME vNext_Partner

cd ~/projects/my-workspace    # vnext.config.json (core) + vnext.partner.config.json (partner)
wf update                     # core with the "core" profile, then partner with the "partner" profile

Backward Compatibility

Existing single-domain configurations are automatically migrated to the new format.
A default domain is created with your existing settings.
If you don't use multidomain features, everything works exactly as before.
All wf config get/set commands continue to work (they operate on the active domain).

Migration

When upgrading from an older version, the CLI automatically migrates the config file:

Before (old flat format):

{
  "API_BASE_URL": "http://localhost:4201",
  "DB_NAME": "vNext_WorkflowDb"
}

After (new domain-aware format):

{
  "ACTIVE_DOMAIN": "default",
  "DOMAINS": [
    {
      "DOMAIN_NAME": "default",
      "AUTO_DISCOVER": true,
      "API_BASE_URL": "http://localhost:4201",
      "API_VERSION": "v1",
      "DB_HOST": "localhost",
      "DB_PORT": 5432,
      "DB_NAME": "vNext_WorkflowDb",
      "DB_USER": "postgres",
      "DB_PASSWORD": "postgres",
      "USE_DOCKER": false,
      "DOCKER_POSTGRES_CONTAINER": "vnext-postgres",
      "DEBUG_MODE": false
    }
  ]
}

Your existing values are preserved. Any missing keys are filled in from defaults (11 keys total).

No manual action is required. The migration happens automatically on first run.

Domain Commands

Command	Description
`wf domain active`	Show active domain name
`wf domain list`	List all domains with active indicator
`wf domain --list`	List all domains (shorthand)
`wf domain add <name> [options]`	Add a new domain
`wf domain use <name>`	Switch active domain
`wf domain remove <name>`	Remove a domain

Available Options for `wf domain add`

Option	Description
`--API_BASE_URL <url>`	API base URL
`--API_VERSION <version>`	API version
`--DB_HOST <host>`	Database host
`--DB_PORT <port>`	Database port
`--DB_NAME <name>`	Database name
`--DB_USER <user>`	Database user
`--DB_PASSWORD <password>`	Database password
`--AUTO_DISCOVER <true/false>`	Auto discover components
`--USE_DOCKER <true/false>`	Use Docker for DB
`--DOCKER_POSTGRES_CONTAINER <name>`	Docker container name
`--DEBUG_MODE <true/false>`	Debug mode

Unspecified options inherit from the default domain.

🆘 Troubleshooting

"vnext.config.json not found"

# Make sure you're in the correct directory
pwd

# Check if vnext.config.json exists
ls -la vnext.config.json

# Check current working directory
wf config get PROJECT_ROOT

"Files not found" (When using on another PC)

# Just cd into the project directory
cd /Users/NewUser/path/to/project

# Verify
wf check

Note: No need to set PROJECT_ROOT - just cd into your project folder.

"No CLI domain profile for … — skipped"

The solution's domain has no matching profile. Create one:

wf domain add <domain> --API_BASE_URL http://localhost:4201 --DB_NAME <db>
wf domain list

"DOMAIN_MISMATCH" in the error table

A component's domain field is missing or differs from the domain of the solution file whose componentsRoot contains it. Fix the component's domain (or move the file to the right solution folder) and re-run.

"Domain "x" not found in this workspace"

--domain names a domain that no solution file in the current directory declares. The message lists the available domains.

"Cannot connect to API"

# Check API
curl http://localhost:4201/api/v1/health

# Check config
wf config get API_BASE_URL

"Database connection failed"

# Check Docker container
docker ps | grep postgres

# Start container
docker start vnext-postgres

# Check config
wf config get USE_DOCKER
wf config get DOCKER_POSTGRES_CONTAINER

"npm link not working"

# Use alias (wf or vnext)
echo 'alias wf="node $(pwd)/bin/workflow.js"' >> ~/.bashrc
echo 'alias vnext="node $(pwd)/bin/workflow.js"' >> ~/.bashrc
source ~/.bashrc

🚀 Creating a New Version

The project uses automated versioning and publishing via GitHub Actions. Follow these steps to create and publish a new version:

Method 1: Using Release Branches (Recommended)

Create a release branch following the pattern release-vX.Y:

git checkout -b release-v1.0
git push origin release-v1.0

Push to the release branch - The workflow will automatically:
- Calculate the next patch version (e.g., 1.0.0, 1.0.1, 1.0.2)
- Build and validate the package
- Publish to NPM and/or GitHub Packages
- Create a Git tag (e.g., v1.0.0)
- Create a GitHub release

Method 2: Manual Workflow Dispatch

Go to GitHub Actions in your repository
Select "Build and Publish to NPM" workflow
Click "Run workflow"
Configure options:
- Version Override: Optional. Leave empty for auto-calculation (e.g., 1.0.6)
- Force Publish: Set to true if you want to republish an existing version
- Target Registry: Choose npmjs, github, or both
Click "Run workflow"

Version Calculation

The workflow automatically calculates versions:

From branch name: If branch is release-v1.0, it will find the next available patch version (e.g., 1.0.0, 1.0.1, 1.0.2)
From package.json: If branch doesn't match the pattern, it increments the patch version from package.json

After Publishing

Once published, the new version will be:

✅ Available on NPM: npm install -g @burgan-tech/vnext-workflow-cli@1.0.0
✅ Tagged in Git: v1.0.0
✅ Released on GitHub with release notes

Workflow Requirements

The workflow requires these secrets to be configured in GitHub repository settings:

NPM_TOKEN (optional): For publishing to NPM. If not set, only GitHub Packages will be used.
SONAR_TOKEN (optional): For code quality analysis
SONAR_HOST_URL (optional): SonarQube server URL

Workflow Steps

The build and publish workflow performs these steps:

✅ Checkout code with full Git history
✅ Calculate version from branch or package.json
✅ Validate syntax - Checks all JavaScript files
✅ Run linting (if available)
✅ Run tests (if available)
✅ Build package (if build script exists)
✅ Publish to registry (NPM and/or GitHub Packages)
✅ Create Git tag (e.g., v1.0.0)
✅ Create GitHub release with release notes

📋 Development

Project Structure

vnext-workflow-cli/
├── bin/
│   └── workflow.js          # CLI entry point
├── src/
│   ├── commands/            # Command implementations
│   │   ├── check.js
│   │   ├── config.js
│   │   ├── csx.js
│   │   ├── domain.js        # Multidomain management
│   │   ├── reset.js
│   │   ├── sync.js
│   │   └── update.js
│   └── lib/                 # Library modules
│       ├── api.js           # API client (publish, reinitialize)
│       ├── config.js        # CLI configuration
│       ├── csx.js           # CSX processing
│       ├── db.js            # Database operations
│       ├── discover.js      # Component discovery
│       ├── solutions.js     # Solution-file discovery + per-domain runner
│       ├── vnextConfig.js   # Solution file (vnext*.config.json) parser
│       └── workflow.js      # Workflow processing
├── .github/
│   └── workflows/           # GitHub Actions workflows
│       ├── build-and-publish.yml
│       └── check-sonar.yml
├── package.json
└── README.md

Local Development

# Clone and install
git clone https://github.com/burgan-tech/vnext-workflow-cli.git
cd vnext-workflow-cli
npm install
npm link

# Test the CLI
wf --version
wf check

# Run development
npm run dev

📝 License

MIT License - see LICENSE for details.

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
bin		bin
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

🚀 vNext Workflow CLI

📦 Installation

Install from NPM (Recommended)

Install from Source

Requirements

📄 vnext.config.json (Required)

Example Configuration

Key Properties

Component Discovery

Multiple solutions in one workspace

⚡ Quick Start

Initial Configuration

Basic Usage

📖 Commands

wf check

wf sync

wf update [options]

wf reset

wf csx [options]

wf config <action> [key] [value]

wf domain [action] [name] [options]

⚙️ Configuration Variables

Config File Format

All Available Settings (Per Domain)

Quick Setup Examples

💡 Usage Scenarios

1. First Time Setup

2. Daily Development - Changed Files

3. Update All Components

4. Reset Specific Component Type

5. Only Update CSX in JSONs (No API)

5b. Update a Whole Feature Folder (No Git Needed)

6. Multidomain Workflow

🔄 Command Comparison

🔀 Multidomain Support

Overview

Solution → Profile Resolution

Backward Compatibility

Migration

Domain Commands

Available Options for wf domain add

🆘 Troubleshooting

"vnext.config.json not found"

"Files not found" (When using on another PC)

"No CLI domain profile for … — skipped"

"DOMAIN_MISMATCH" in the error table

"Domain "x" not found in this workspace"

"Cannot connect to API"

"Database connection failed"

"npm link not working"

🚀 Creating a New Version

Method 1: Using Release Branches (Recommended)

Method 2: Manual Workflow Dispatch

Version Calculation

After Publishing

Workflow Requirements

Workflow Steps

📋 Development

Project Structure

Local Development

📝 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`wf check`

`wf sync`

`wf update [options]`

`wf reset`

`wf csx [options]`

`wf config <action> [key] [value]`

`wf domain [action] [name] [options]`

Available Options for `wf domain add`