Bizmanage CLI

A command-line interface tool for building customizations for the Bizmanage SaaS platform locally. The CLI helps developers sync code between their local filesystem and the Bizmanage platform API.

Features

• 🔐 Authentication Management - Login/logout with support for multiple environment aliases
• ⬇️ Pull Customizations - Download customizations from the platform to local files
• ⬆️ Push Customizations - Upload local customizations with validation and testing
• 📋 Metadata Validation - Strict schema validation using Zod
• 🧪 Testing Integration - Automatic test execution before deployment
• 📁 Organized Structure - Clean file organization with metadata files
• 🔄 Smart Caching - Hash-based change detection for efficient syncing with cache management

Installation

From npm

npm install -g bizmanage-cli

Using npx (no installation required)

npx bizmanage-cli --help
npx bizmanage-cli login

Local Development

git clone https://github.com/yourusername/bizmanage-cli.git
cd bizmanage-cli
npm install
npm run build
npm link

Quick Start

1. Login to your Bizmanage instance:

   bizmanage login

2. Pull existing customizations:

   bizmanage pull

3. Make changes to your code in the ./src directory

4. Push changes back to the platform:

   bizmanage push

Commands

bizmanage login

Save your API key and test authentication with the Bizmanage platform.

bizmanage login [options]

How it works:

1. Prompts for your Instance URL and API Key
2. Tests authentication using GET /restapi/ping
3. Saves API key securely only if authentication succeeds

Options:

• -a, --alias <alias> - Configuration alias (default: "default")

Example:

# Login with default alias
bizmanage login

# Login with custom alias for different environments
bizmanage login --alias production
bizmanage login --alias development

bizmanage logout

Delete saved API key and authentication configuration.

bizmanage logout [options]

How it works:

1. Removes the saved API key from secure storage
2. Deletes all associated configuration data

Options:

• -a, --alias <alias> - Configuration alias to remove (default: "default")
• --all - Remove all saved API keys and configurations

Examples:

# Logout from default configuration
bizmanage logout

# Logout from specific alias
bizmanage logout --alias production

# Remove all saved API keys
bizmanage logout --all

bizmanage init

Initialize a new Bizmanage project structure with all necessary directories and configuration files.

bizmanage init [project-name] [options]

Arguments:

• [project-name] - Optional project name. If not provided, you'll be prompted to enter one.

Options:

• -a, --alias <alias> - Configuration alias to use (default: "default")
• --force - Overwrite existing project files

How it works:

1. Prompts for project name (if not provided) and description
2. Creates project directory structure (src/objects, src/backend, src/reports, src/pages)
3. Generates bizmanage.config.json with project metadata
4. Creates .gitignore file configured for Bizmanage projects
5. Sets up .bizmanage directory for cache and internal files

Created Structure:

project-name/
├── src/
│   ├── objects/
│   ├── backend/
│   ├── reports/
│   └── pages/
├── .bizmanage/          # Cache and internal files (auto-created)
├── bizmanage.config.json # Project configuration
└── .gitignore           # Pre-configured ignore rules

Examples:

# Interactive setup (prompts for name)
bizmanage init

# Initialize with project name
bizmanage init my-project

# Initialize in current directory
bizmanage init . --force

# Initialize with specific environment alias
bizmanage init my-project --alias production

bizmanage status

Show current login status and saved API keys.

bizmanage status [options]

Options:

• -p, --path <path> - Project path (default: current directory)
• --auth-only - Show only authentication status
• --changes-only - Show only file changes

Shows:

• All saved configuration aliases
• Instance URLs for each alias
• Masked API keys (for security)
• File change statistics (changed, new, deleted files)
• Changes grouped by type (objects, backend scripts, reports, pages)

Examples:

# Full status (auth + changes)
bizmanage status

# Show only authentication info
bizmanage status --auth-only

# Show only file changes
bizmanage status --changes-only

# Check status in different project
bizmanage status -p /path/to/project

bizmanage status-detail

Show detailed authentication, connection, and project status with comprehensive information.

bizmanage status-detail [options]

Options:

• -a, --alias <alias> - Configuration alias to check (default: "default")
• --project - Show detailed project status if in a project directory
• --api - Test API endpoints and show available data

Shows:

• Detailed configuration information
• API connection test results
• Project metadata (name, description, created date)
• Last pull/push timestamps
• Local item counts by type
• Available API endpoints (with --api flag)

Examples:

# Basic detailed status
bizmanage status-detail

# Check specific alias
bizmanage status-detail --alias production

# Include project information
bizmanage status-detail --project

# Test API endpoints
bizmanage status-detail --api

# Full detailed report
bizmanage status-detail --project --api

bizmanage clear-cache

Clear the hash cache, making all files behave as if they are new. This is useful when you want to force a complete re-sync of all files on the next pull or push operation.

bizmanage clear-cache [options]

Aliases:

• bizmanage rm-cache
• bizmanage cache-clear

Options:

• -p, --path <path> - Project path (default: current directory)

How it works:

1. Removes all file hashes from the cache (.bizmanage/file-hashes.json)
2. Shows statistics about how many files were cleared
3. Next pull/push will treat all files as new/changed

When to use:

• Force a complete re-sync of all files
• After manually modifying files outside the CLI
• Troubleshooting sync issues
• Reset after resolving merge conflicts

Examples:

# Clear cache in current directory
bizmanage clear-cache

# Clear cache in specific project
bizmanage clear-cache -p /path/to/project

# Using aliases
bizmanage rm-cache
bizmanage cache-clear

bizmanage validate

Validate project files or a specific file for schema compliance and best practices. By default, only validates changed files for faster validation during development.

bizmanage validate [options]

Options:

• -f, --file <path> - Validate a specific file instead of entire project
• -p, --path <path> - Project path (default: current directory)
• -a, --all - Validate all files (default: only changed files)

Features:

• Smart validation - By default, only validates changed/new files for faster feedback
• Auto-detection - Automatically detects customization type from file path
• Schema validation - Validates against Zod schemas for each customization type
• Business logic checks - Additional validation rules beyond basic schema
• JavaScript syntax - Checks for syntax errors in .js files (supports top-level await)
• SQL validation - Basic SQL query validation for reports
• HTML validation - Tag balance checking for pages
• Extensible - Easy to add new validation rules per customization type

Customization Types Detected:

• object - Object definitions (definition.json)
• action - Actions (.js and .json files)
• field - Field definitions
• backend-script - Backend scripts (.js and .json)
• report - Reports (.sql and .json)
• page - Pages (.html and .json)

Examples:

# Validate only changed files (fast, recommended for development)
bizmanage validate

# Validate all files in the project (full check)
bizmanage validate --all

# Validate a specific file
bizmanage validate -f src/backend/my-script.js

# Validate a specific metadata file
bizmanage validate -f src/objects/custom-table/definition.json

# Validate project in a different directory
bizmanage validate -p /path/to/project

Output:

• ✅ Success with warnings count (if any)
• ❌ Errors grouped by customization type
• ⚠️ Warnings grouped by customization type
• Validation errors include file path and specific issue location

bizmanage test

Test authentication and connection to the Bizmanage API.

bizmanage test [options]

Options:

• -a, --alias <alias> - Test specific alias configuration (default: "default")
• --ping-only - Only run the ping test without detailed report
• --verbose - Show verbose output

Examples:

# Test default configuration
bizmanage test

# Test specific alias
bizmanage test --alias production

# Quick ping test only
bizmanage test --ping-only

# Verbose output with configuration details
bizmanage test --verbose

API Endpoint Tested:

• GET /restapi/ping - Returns 200 if authenticated, 403 if not authenticated

bizmanage pull

Download customizations from the platform to your local filesystem.

bizmanage pull [options]

Options:

• -a, --alias <alias> - Configuration alias to use (default: "default")
• -o, --output <path> - Output directory (default: "./src")
• -d, --delay <ms> - Delay in milliseconds between API requests (default: 0)
• --init - Initialize a new project structure
• -f, --force - Force pull even when local changes exist (overwrites local files)

Example:

# Pull to default ./src directory (fast, no delay)
bizmanage pull

# Pull to custom directory
bizmanage pull --output ./my-customizations

# Pull using specific environment
bizmanage pull --alias production

# Pull with rate limiting (safe for large projects or rate-limited APIs)
bizmanage pull --delay 100

# Pull with slower rate limiting for heavily rate-limited instances
bizmanage pull --delay 500

# Pull and overwrite local changes (use only after committing/pushing your work)
bizmanage pull -f

Pull safety: If local changes are detected, the pull is blocked to avoid overwriting your work. Commit and push your changes first, or rerun with -f to forcefully overwrite local files (the CLI clears its hash cache in force mode so every pulled file is rewritten).

bizmanage push

Push local customizations to Bizmanage platform with validation and testing. By default, only pushes changed files for faster deployment.

bizmanage push [options]

Options:

• -a, --alias <alias> - Configuration alias to use (default: "default")
• -s, --source <path> - Source directory (default: current directory)
• --all - Push all files (default: only changed files)
• --skip-tests - Skip running tests before deploy
• --skip-validation - Skip metadata validation

Features:

• Smart deployment - By default, only pushes changed/new files for faster deployments
• Type-specific push - Each customization type (objects, actions, scripts, reports, pages) has its own push logic
• Hash tracking - Successfully pushed files are marked as unchanged to avoid redundant pushes
• Validation - Validates files before pushing (can be skipped with --skip-validation)
• Testing - Runs npm test before pushing (can be skipped with --skip-tests)
• Detailed feedback - Shows which files were pushed and any errors encountered

Push Process:

1. Validation - Validates changed files (or all files with --all)
2. Testing - Runs npm test to ensure code quality
3. Deployment - Pushes files to platform via API
4. Hash Update - Updates file hashes after successful push

Examples:

# Standard push - only changed files with validation and testing
bizmanage push

# Push all files (full deployment)
bizmanage push --all

# Push skipping tests (faster, but not recommended for production)
bizmanage push --skip-tests

# Push skipping validation and tests (development only)
bizmanage push --skip-validation --skip-tests

# Push to specific environment
bizmanage push --alias production

# Push from custom project directory
bizmanage push --source /path/to/project

Project Structure

After running bizmanage pull, your local directory will be organized as follows:

./src/
├── reports/
│   ├── meta.json                 # Metadata for all reports
│   ├── sales-report.sql          # Report SQL code
│   └── user-analytics.sql
├── pages/
│   ├── meta.json                 # Metadata for all pages
│   ├── dashboard.html            # Page HTML/JS code
│   └── settings-page.html
├── backend-scripts/
│   ├── meta.json                 # Metadata for all scripts
│   ├── data-processor.js         # Backend script code
│   └── email-scheduler.js
└── fields/
    ├── meta.json                 # Metadata for all fields
    ├── custom-field-1.json       # Field configuration
    └── validation-field.json

Each meta.json file contains:

• Scope information (reports, pages, backend-scripts, fields)
• List of items with their metadata
• Generation timestamp
• File mappings

Version Control Strategy

⚠️ Important: The pulled data should NOT be committed to your repository!

The .gitignore file is configured to exclude:

• src/objects/ - Generated table/view definitions and actions
• src/backend/ - Generated backend scripts
• src/reports/ - Generated SQL reports
• src/pages/ - Generated HTML pages
• bizmanage.config.json - Project configuration (may contain sensitive URLs)

Why exclude pulled data?

1. Instance-specific: Each developer should pull from their own Bizmanage instance
2. Sensitive information: May contain API keys, instance URLs, or business logic
3. Generated content: These files are automatically created and should not be manually edited in version control
4. Environment differences: Different instances may have different customizations

Recommended workflow:

# Each developer on your team should:
git clone your-repo
cd your-repo
npm install

# Login to their own Bizmanage instance  
bizmanage login

# Pull their own data
bizmanage pull --init

# Work with the pulled files locally
# Make changes and push back to their instance
bizmanage push

What IS committed to git:

• CLI source code and configuration
• Documentation and examples
• Build scripts and dependencies
• Empty directories with .gitkeep files to maintain structure

Metadata Schema

Backend Script Metadata Example

{
  "description": "A script that processes user data",
  "version": "1.0.0",
  "author": "[email protected]",
  "tags": ["data-processing", "automation"],
  "entryPoint": "processUserData",
  "dependencies": ["lodash", "moment"],
  "permissions": ["read", "write"],
  "schedule": {
    "enabled": true,
    "cron": "0 2 * * *",
    "timezone": "UTC"
  },
  "timeout": 300,
  "memory": 512,
  "retryPolicy": {
    "maxRetries": 3,
    "retryDelay": 1000,
    "exponentialBackoff": true
  }
}

Development

Setup for Development

1. Clone the repository:

   git clone <repository-url>
   cd bizmanage-cli

2. Install dependencies:

   npm install

3. Start development mode:

   npm run dev

4. Link for local testing:

   npm run build
   npm link

Available Scripts

• npm run build - Build TypeScript to JavaScript
• npm run dev - Watch mode for development
• npm start - Run the CLI locally
• npm test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run lint - Lint the code
• npm run lint:fix - Fix linting issues

Testing

Create tests in the tests/ directory:

npm test

For continuous testing during development:

npm run test:watch

Publishing

Prerequisites

1. Create npm account: Sign up at npmjs.com

2. Login to npm:

   npm login

3. Verify your email with npm if you haven't already

4. Update package.json:

   • Set your name and email in the "author" field
   • Update repository URLs to match your GitHub repo
   • Verify the package name is available on npm

Publication Steps

1. Run pre-publish validation:

   npm run publish-check

2. Update version (choose appropriate bump):

   npm version patch  # Bug fixes (1.0.0 → 1.0.1)
   npm version minor  # New features (1.0.0 → 1.1.0)  
   npm version major  # Breaking changes (1.0.0 → 2.0.0)

3. Publish to npm:

   npm publish

4. Verify publication:

   npm info bizmanage-cli

Automated Publishing with GitHub Actions

Create .github/workflows/publish.yml:

name: Publish to NPM

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm run build
      - run: npm test
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Beta/Alpha Releases

For pre-release versions:

# Create beta version
npm version prerelease --preid=beta  # 1.0.0 → 1.0.1-beta.0
npm publish --tag beta

# Install beta version
npm install -g bizmanage-cli@beta

Configuration

Verbosity and Debugging

The CLI supports multiple verbosity levels to help with debugging and development:

# Default logging (INFO level) - shows basic operations
bizmanage login

# Silent mode - only shows errors
bizmanage login --silent

# Verbose mode - shows INFO level messages
bizmanage login -v
bizmanage login --verbose

# Very verbose mode - shows DEBUG level messages (includes HTTP requests/responses)
bizmanage login -vv
bizmanage login --very-verbose

# Extra verbose mode - shows TRACE level messages (maximum detail)
bizmanage login -vvv
bizmanage login --extra-verbose

# Debug mode - same as very verbose, useful for development
bizmanage login --debug

# Include timestamps in log output
bizmanage login --log-timestamps

# Combine options for detailed debugging
bizmanage login -vv --log-timestamps

Log Levels:

• ERROR (--silent): Only critical errors
• WARN (default): Errors and warnings
• INFO (-v): Errors, warnings, and informational messages
• DEBUG (-vv, --debug): All above plus HTTP requests/responses, service details
• TRACE (-vvv): Maximum verbosity including internal operations

Features:

• Built on Winston for robust logging
• Automatic header sanitization for security (API keys are redacted)
• Color-coded output for easy reading
• Structured data logging in JSON format for complex objects
• Response time tracking for API calls
• Child loggers with prefixes for different services

The CLI stores authentication configurations in ~/.bizmanage/config.json. This allows you to manage multiple environments:

{
  "default": {
    "instanceUrl": "https://api.bizmanage.com",
    "apiKey": "your-api-key"
  },
  "development": {
    "instanceUrl": "https://dev-api.bizmanage.com",
    "apiKey": "dev-api-key"
  },
  "production": {
    "instanceUrl": "https://prod-api.bizmanage.com",
    "apiKey": "prod-api-key"
  }
}

API Integration

The CLI communicates with the Bizmanage platform through REST API endpoints:

• GET /api/customizations/{scope} - Fetch customizations
• POST /api/customizations/deploy - Deploy customizations
• GET /api/auth/validate - Validate authentication

Validation

All metadata files are validated using Zod schemas before deployment:

• Required fields: description, version, author, tags
• Version format: Must follow semver (e.g., "1.0.0")
• Type-specific validation: Each customization type has its own schema
• File integrity: Ensures all referenced files exist

Error Handling

The CLI provides detailed error messages for common issues:

• Authentication failures
• Network connectivity problems
• Validation errors with specific field information
• Test failures with output
• File system errors

Troubleshooting

Common Issues

1. Authentication Error:

   # Re-authenticate
   bizmanage logout
   bizmanage login

2. Validation Failures:

   # Check metadata format
   bizmanage push --skip-tests  # To isolate validation issues

3. Test Failures:

   # Run tests separately
   npm test

4. Network Issues:

   • Check your internet connection
   • Verify the instance URL is correct
   • Ensure API endpoints are accessible

Getting Help

• Check the command help: bizmanage <command> --help
• Review error messages for specific guidance
• Ensure all dependencies are properly installed

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Add tests for new functionality
5. Run the test suite: npm test
6. Run the linter: npm run lint
7. Commit your changes: git commit -am 'Add some feature'
8. Push to the branch: git push origin feature-name
9. Submit a pull request

Development Guidelines

• Follow TypeScript best practices
• Add JSDoc comments for public APIs
• Write tests for new features
• Update documentation as needed
• Follow the existing code style

Code Style

This project uses ESLint and TypeScript for code quality. Run:

npm run lint        # Check for issues
npm run lint:fix    # Fix auto-fixable issues

Changelog

v1.0.0

• Initial release
• Login/logout functionality with multi-alias support
• Pull customizations from platform
• Push customizations with validation and testing
• Comprehensive Zod schema validation
• CLI with colored output and loading indicators

Support

• 📧 Issues: GitHub Issues
• 📖 Documentation: README.md
• 💬 Discussions: GitHub Discussions

Security

If you discover a security vulnerability, please send an email to [email protected] instead of using the issue tracker.

Acknowledgments

• Built with Commander.js for CLI framework
• Uses Inquirer.js for interactive prompts
• Validation powered by Zod
• File operations with fs-extra