Genval CLI

Transform business workflows into deployable cloud infrastructure

A powerful TypeScript CLI tool that compiles semantic business workflows into cloud infrastructure code (Terraform, CloudFormation) for deployment to AWS, Azure, GCP, or Cloudflare.

Features

✨ Interactive CLI - Claude Code-style experience with built-in tab completion
🔄 Semantic Workflows - Define business logic using JSON-LD format
🚀 Multi-Cloud Support - Deploy to AWS, Azure, GCP, or Cloudflare
⚡ Infrastructure as Code - Generate Terraform or CloudFormation
🔐 Secure Secrets - Built-in encrypted secrets management
📊 Real-time Validation - Instant feedback on workflow syntax and dependencies
🎯 Session History - Command history and project context awareness

Installation

npm install -g @genval/cli

Quick Start

# Start the interactive CLI
genval

# In the interactive session:
genval:my-project> init --name my-workflows --provider aws
genval:my-project> create customer-onboarding --template notifications
genval:my-project> validate customer-onboarding
genval:my-project> compile customer-onboarding --format terraform
genval:my-project> deploy customer-onboarding --environment prod

Workflow-Driven Development

Genval enables you to focus on business logic rather than infrastructure complexity:

{
  "@context": { "genval": "https://genval.ai/context/v1" },
  "@type": "Workflow",
  "@id": "customer-onboarding",
  "name": "Customer Onboarding",
  "description": "Automated customer onboarding with validation and notifications",
  "steps": [
    {
      "@id": "validate-data",
      "capability": "data-processing",
      "operation": "validate",
      "inputs": { "schema": { "type": "object", "required": ["email", "name"] } }
    },
    {
      "@id": "create-account", 
      "capability": "storage",
      "operation": "create",
      "dependencies": ["validate-data"]
    },
    {
      "@id": "send-welcome",
      "capability": "notifications", 
      "operation": "send-email",
      "dependencies": ["create-account"]
    }
  ]
}

This workflow automatically generates:

• Database schemas and operations
• API endpoints and validation logic
• Email service integration
• Monitoring and error handling
• Cloud deployment configuration

Commands Reference

Core Commands

init [options]

Initialize a new Genval workflow project with interactive setup.

# Start the interactive CLI and run init
genval
genval:> init                              # Interactive setup
genval:> init --name my-project           # Specify project name
genval:> init --provider aws              # Pre-select cloud provider
genval:> init -n workflows -p gcp         # Shorthand flags

Options:

• -n, --name <name> - Project name (defaults to current directory)
• -p, --provider <provider> - Cloud provider: aws, azure, gcp, cloudflare

Creates:

• genval.json - Project configuration
• workflows/ - Workflow definitions directory
• examples/ - Sample workflow templates
• .genval/ - Generated files and build artifacts

create <workflow-name> [options]

Create a new workflow definition with interactive capability selection.

# In the interactive session:
genval:my-project> create customer-onboarding                    # Interactive creation
genval:my-project> create data-pipeline --template data-processing  # Use specific template
genval:my-project> create api-service -t api-integration         # Shorthand template

Options:

• -t, --template <template> - Workflow template:
  • data-processing - ETL, validation, transformation
  • api-integration - REST APIs, webhooks, external services
  • notifications - Email, SMS, push notifications
  • storage - Databases, file storage, caching
  • authentication - User auth, JWT, OAuth flows
  • monitoring - Logging, metrics, alerting

Features:

• Interactive capability selection
• Automatic dependency resolution
• JSON-LD schema validation
• Integration with existing workflows

validate [workflow] [options]

Validate workflow semantics, dependencies, and cloud compatibility.

# In the interactive session:
genval:my-project> validate                          # Validate all workflows
genval:my-project> validate customer-onboarding     # Validate specific workflow
genval:my-project> validate --all                    # Explicit all validation

Options:

• -a, --all - Validate all workflows in the project

Validation Checks:

• ✅ JSON-LD schema compliance
• ✅ Step dependency resolution
• ✅ Capability requirement verification
• ✅ Input/output data type compatibility
• ✅ Cloud provider resource availability
• ✅ Security and permission requirements

compile <workflow> [options]

Compile workflows into deployable cloud infrastructure code.

# In the interactive session:
genval:my-project> compile customer-onboarding                      # Default compilation
genval:my-project> compile data-pipeline --format terraform         # Specify format
genval:my-project> compile api-service -o ./infra -f cloudformation # Custom output

Options:

• -o, --output <dir> - Output directory (default: .genval/compiled)
• -f, --format <format> - Infrastructure format: terraform, cloudformation

Generated Assets:

• Infrastructure as Code files (.tf or .yaml)
• Environment-specific variable files
• Deployment scripts and documentation
• Security policies and IAM configurations
• Monitoring and alerting configurations

deploy <workflow> [options]

Deploy compiled infrastructure to your cloud provider.

# In the interactive session:
genval:my-project> deploy customer-onboarding --environment prod    # Production deployment
genval:my-project> deploy data-pipeline -e dev --dry-run           # Preview changes
genval:my-project> deploy api-service --dry-run                     # Plan-only mode

Options:

• -e, --environment <env> - Target environment: dev, staging, prod
• --dry-run - Preview deployment plan without executing changes

Prerequisites:

• Compiled infrastructure (compile command executed in interactive session)
• Cloud provider credentials configured
• Appropriate IAM permissions for resource creation
• Environment-specific configuration files

Utility Commands

secrets [options]

Securely manage workflow secrets and cloud credentials.

# In the interactive session:
genval:my-project> secrets --list                    # List all secret keys
genval:my-project> secrets --set DATABASE_PASSWORD   # Set new secret (prompts for value)
genval:my-project> secrets --delete OLD_API_KEY      # Remove secret permanently

Options:

• -l, --list - List all stored secret keys (values remain hidden)
• -s, --set <key> - Set a secret value (interactive prompt for value)
• -d, --delete <key> - Delete a secret permanently

Security Features:

• 🔐 AES-256 encryption for all secret values
• 🔑 Local storage in .genval/secrets.json
• 🚫 Secrets never logged or exposed in output
• 📝 Reference in workflows using {{SECRET_NAME}} syntax

Tab Completion

The interactive CLI includes built-in intelligent tab completion for enhanced developer experience.

Completion Features:

• 🎯 Command completion (<TAB> after prompt)
• 📁 Workflow name completion (validate <TAB>)
• ⚙️ Option completion (--provider <TAB>)
• 📂 Directory completion (--output <TAB>)
• 🔄 Context-aware suggestions

Tab completion is automatically enabled in the interactive session - no setup required!

Capabilities & Use Cases

Data Processing

ETL pipelines, data validation, transformations

{
  "capability": "data-processing",
  "operations": ["validate", "transform", "filter", "aggregate"]
}

API Integration

REST APIs, webhooks, external service integration

{
  "capability": "api-integration", 
  "operations": ["http-request", "webhook", "graphql", "soap"]
}

Storage

Databases, file storage, caching, data persistence

{
  "capability": "storage",
  "operations": ["create", "read", "update", "delete", "cache"]
}

Notifications

Email, SMS, push notifications, communication workflows

{
  "capability": "notifications",
  "operations": ["send-email", "send-sms", "push-notification", "slack"]
}

Authentication

User authentication, JWT tokens, OAuth flows

{
  "capability": "authentication", 
  "operations": ["login", "logout", "jwt-validate", "oauth-flow"]
}

Monitoring

Logging, metrics collection, alerting, observability

{
  "capability": "monitoring",
  "operations": ["log-event", "metric", "alert", "trace"]
}

Real-World Examples

E-commerce Order Processing

genval
genval:my-project> create order-processing --template data-processing
# Generates: payment validation → inventory check → fulfillment → notifications

API Gateway with Auth

genval
genval:my-project> create api-gateway --template api-integration
# Generates: request routing → authentication → rate limiting → responses

Data Analytics Pipeline

genval
genval:my-project> create analytics-pipeline --template data-processing  
# Generates: data ingestion → transformation → storage → reporting

User Registration System

genval
genval:my-project> create user-registration --template authentication
# Generates: validation → account creation → email verification → onboarding

Project Structure

my-genval-project/
├── genval.json                 # Project configuration
├── workflows/                  # Workflow definitions
│   ├── customer-onboarding.json
│   ├── data-pipeline.json
│   └── notification-system.json
├── capabilities/               # Custom capability definitions
│   └── custom-integrations/
├── examples/                   # Sample workflows and templates
│   ├── customer-onboarding.json
│   └── data-pipeline.json
└── .genval/                    # Generated files (gitignored)
    ├── compiled/               # Generated infrastructure code
    │   ├── terraform/
    │   └── cloudformation/
    ├── deployments.json        # Deployment history
    └── secrets.json            # Encrypted secrets

Configuration

genval.json

{
  "name": "my-workflows",
  "version": "1.0.0", 
  "description": "Business workflow automation",
  "provider": "aws",
  "workflows": ["customer-onboarding", "data-pipeline"],
  "capabilities": ["data-processing", "notifications"],
  "environments": {
    "dev": { "region": "us-west-2" },
    "prod": { "region": "us-east-1" }
  }
}

Cloud Provider Setup

AWS

# Configure AWS credentials
aws configure

# Or use environment variables
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
export AWS_DEFAULT_REGION=us-west-2

Azure

# Azure CLI login
az login

# Or use service principal
export AZURE_CLIENT_ID=your_client_id
export AZURE_CLIENT_SECRET=your_secret
export AZURE_TENANT_ID=your_tenant

Google Cloud

# Authenticate with gcloud
gcloud auth application-default login

# Or use service account
export GOOGLE_APPLICATION_CREDENTIALS=path/to/key.json

Cloudflare

# Set Cloudflare credentials
export CLOUDFLARE_API_TOKEN=your_token
export CLOUDFLARE_ZONE_ID=your_zone_id

Advanced Features

Custom Capabilities

Extend Genval with custom capabilities for your specific use cases:

{
  "@type": "CustomCapability",
  "@id": "payment-processing",
  "name": "Payment Processing",
  "operations": ["charge", "refund", "subscription"],
  "provider": "stripe",
  "configuration": {
    "api_key": "{{STRIPE_API_KEY}}",
    "webhook_secret": "{{STRIPE_WEBHOOK_SECRET}}"
  }
}

Environment-Specific Deployments

Configure different settings per environment:

{
  "environments": {
    "dev": {
      "provider": "aws",
      "region": "us-west-2", 
      "instance_type": "t3.micro"
    },
    "prod": {
      "provider": "aws",
      "region": "us-east-1",
      "instance_type": "c5.large",
      "auto_scaling": true
    }
  }
}

Workflow Dependencies

Chain workflows together for complex business processes:

{
  "dependencies": ["user-registration", "email-verification"],
  "triggers": ["webhook", "schedule", "manual"],
  "error_handling": "retry_with_backoff"
}

Troubleshooting

Common Issues

Validation Errors

# Start interactive session and check workflow syntax
genval
genval:my-project> validate your-workflow --verbose

# Verify dependencies
genval:my-project> validate --all

Compilation Failures

# Check cloud provider credentials
aws sts get-caller-identity  # For AWS
az account show             # For Azure

# Verify required permissions in interactive session
genval
genval:my-project> compile --dry-run

Deployment Issues

# Preview changes before deployment in interactive session
genval
genval:my-project> deploy your-workflow --dry-run

# Check deployment logs
tail -f .genval/deploy.log

Debug Mode

# Enable verbose logging
export GENVAL_DEBUG=true
genval
genval:my-project> compile your-workflow

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/genval-ai/genval-cli.git
cd genval-cli

# Install dependencies
npm install

# Build and test
npm run build
npm test

# Test locally
npm link
genval --help

Running Tests

npm test                    # Run all tests
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests
npm run test:e2e           # End-to-end tests

Roadmap

• 🔄 Multi-workflow orchestration - Complex workflow dependencies
• 🎨 Visual workflow designer - Web-based drag-and-drop interface
• 📊 Real-time monitoring - Live workflow execution tracking
• 🤖 AI-powered optimization - Automatic performance improvements
• 🔌 Plugin ecosystem - Community-driven capability extensions
• 📱 Mobile dashboard - Monitor deployments on the go

Community & Support

• 📖 Documentation - Comprehensive guides and API reference
• 💬 Discord Community - Chat with users and maintainers
• 🐛 GitHub Issues - Bug reports and feature requests
• 📧 Email Support - Enterprise support available
• 🎓 Learning Center - Tutorials and best practices

License

MIT License - see LICENSE file for details.

Built with ❤️ by the Genval team

Transform your business logic into cloud infrastructure with confidence.