Skip to content

cli-usage.md

Latest commit

 

History

History
312 lines (223 loc) · 7.07 KB

cli-usage.md

File metadata and controls

312 lines (223 loc) · 7.07 KB

AI-Powered CLI

The ObjectQL CLI provides AI-powered commands to generate and validate applications using natural language.

Overview

The objectql ai command provides interactive and automated application generation with built-in validation and testing.

Prerequisites

Set your OpenAI API key as an environment variable:

export OPENAI_API_KEY=sk-your-api-key-here

Commands

Interactive Mode (Default)

The easiest way to build applications - just type:

objectql ai

This starts an interactive conversational session where you can:

  • Describe what you want to build in natural language
  • Request changes and improvements iteratively
  • Get suggestions for next steps
  • See files generated in real-time

Example Session:

$ objectql ai
💬 ObjectQL AI Assistant

What would you like to build today?
> A blog system with posts, comments, and categories

Great! I'll create a blog system for you...
✓ Generated: post.object.yml
✓ Generated: comment.object.yml  
✓ Generated: category.object.yml
✓ Generated: post.hook.ts
✓ Generated: post.test.ts

What would you like to add or modify?
> Add tags to posts

Adding tag support...
✓ Generated: tag.object.yml
✓ Updated: post.object.yml

Type "done" to finish, or continue refining your app.
> done

📁 Application saved to ./src

Specify Output Directory:

objectql ai ./my-app

One-Shot Generation

Generate a complete application from a single description without interaction:

objectql ai generate -d "A CRM system with customers, contacts, and opportunities" -o ./src

Options:

  • -d, --description <text> - Application description (required)
  • -o, --output <path> - Output directory (default: ./src)
  • -t, --type <type> - Generation type: basic, complete, or custom (default: custom)

Generation Types:

  • basic - Minimal metadata (objects only)
  • complete - Full metadata (objects, forms, views, actions, hooks, tests)
  • custom - AI decides based on description (recommended)

Examples:

# Generate complete CRM
objectql ai generate \
  -d "Customer relationship management with sales pipeline" \
  -t complete \
  -o ./crm

# Generate simple inventory tracker
objectql ai generate \
  -d "Track products with quantities and locations" \
  -t basic

# Let AI decide what's needed
objectql ai generate \
  -d "E-commerce platform with products, orders, and payments"

What Gets Generated:

For a complete application, you get:

  1. Metadata Files (YAML)

    • *.object.yml - Data entities
    • *.validation.yml - Validation rules
    • *.permission.yml - Access control
    • *.workflow.yml - Automation
    • *.data.yml - Seed data

  2. TypeScript Implementation Files

    • *.action.ts - Custom business operations
    • *.hook.ts - Lifecycle triggers (beforeCreate, afterUpdate, etc.)

  3. Test Files

    • *.test.ts - Jest tests for business logic

Validation

Validate existing metadata files with AI-powered analysis:

objectql ai validate ./src

Options:

  • <path> - Path to metadata directory (required)
  • --fix - Automatically fix issues where possible
  • -v, --verbose - Show detailed validation output

What Gets Checked:

  • ✅ YAML syntax
  • ✅ ObjectQL specification compliance
  • ✅ Business logic consistency
  • ✅ Data model best practices
  • ✅ Security considerations
  • ✅ Performance implications
  • ✅ Field type correctness
  • ✅ Relationship integrity

Example:

$ objectql ai validate ./src -v

🔍 Validating metadata files...

✓ user.object.yml - Valid
⚠ order.object.yml - 2 warnings
  - Line 15: Consider adding index on 'customer_id' field for query performance
  - Line 23: 'total' field should use 'currency' type instead of 'number'
  
❌ product.object.yml - 1 error
  - Line 10: Invalid field type 'string', use 'text' instead

📊 Summary:
  Files checked: 3
  Errors: 1
  Warnings: 2
  Info: 0

Chat Assistant

Get help and guidance about ObjectQL concepts:

objectql ai chat

With Initial Prompt:

objectql ai chat -p "How do I create a lookup relationship?"

Example Session:

$ objectql ai chat
🤖 ObjectQL AI Assistant

Ask me anything about ObjectQL!
> How do I add email validation to a field?

You can add email validation in several ways:

1. Use the built-in 'email' field type:
   fields:
     email:
       type: email
       required: true

2. Or add validation rules:
   fields:
     contact_email:
       type: text
       validation:
         format: email
         
> What about custom validation logic?

For custom validation, use a validation hook...

Complete Workflow Example

Here's a complete workflow from generation to deployment:

# 1. Set API key
export OPENAI_API_KEY=sk-your-key

# 2. Generate application (interactive)
objectql ai
> A project management system with tasks, projects, and teams
> done

# 3. Validate generated files
objectql ai validate ./src -v

# 4. Fix any issues
objectql ai validate ./src --fix

# 5. Test the application
objectql serve

# 6. Get help if needed
objectql ai chat -p "How do I add user authentication?"

Tips & Best Practices

Writing Good Descriptions

Good:

objectql ai generate -d "Inventory management with products, warehouses, stock movements, and reorder points. Include barcode scanning support and low stock alerts."

Not as good:

objectql ai generate -d "inventory app"

Tips:

  • Be specific about entities and relationships
  • Mention key features and business rules
  • Include any special requirements (e.g., "with approval workflow")
  • Specify important fields or attributes

Interactive vs One-Shot

Use Interactive Mode when:

  • Building a new application from scratch
  • Exploring different design options
  • Need to make iterative refinements
  • Want AI guidance and suggestions

Use One-Shot Generation when:

  • You have a clear, detailed requirements document
  • Building a simple, well-defined system
  • Automating app generation in scripts
  • Need quick prototypes

Validation Workflow

Always validate generated files:

# After generation
objectql ai generate -d "..." -o ./src

# Validate
objectql ai validate ./src -v

# Auto-fix common issues
objectql ai validate ./src --fix

# Manually review any remaining issues

Environment Variables

  • OPENAI_API_KEY - Your OpenAI API key (required)
  • OPENAI_MODEL - Model to use (optional, default: gpt-4)
  • OPENAI_TEMPERATURE - Generation temperature 0-1 (optional, default: 0.7)

Fallback Behavior

Without an API key, the CLI will:

  • ✅ Still perform basic YAML syntax validation
  • ❌ Cannot generate applications
  • ❌ Cannot perform AI-powered deep validation
  • ❌ Chat assistant unavailable
# This still works without API key:
objectql ai validate ./src  # Basic YAML syntax check only

Next Steps