Skip to main content

msh ai new

Generate a new .msh asset from natural language description.

Usage​

msh ai new [--name <name>] [--apply] [--path <path>]

Description​

Prompts user for a natural language description and generates a complete .msh file with:

  • Ingest block (appropriate type based on description)
  • Transform block with SQL
  • Tests
  • Contract block (if needed)

Options​

  • --name <name>: Suggested asset ID/name
  • --apply: Write the generated asset to disk automatically
  • --path <path>: Path to save the new .msh file (if --apply is set)

Examples​

Generate Asset (Preview Only)​

msh ai new --name customer_revenue

Interactive Flow:

  1. Prompts for description:

    Describe the asset you want to create:
    > Create an asset that ingests customer data from a REST API
    > and calculates monthly revenue per customer

  2. Generates .msh file using AI

  3. Shows preview:

    name: customer_revenue
    description: Calculates monthly revenue per customer
    ingest:
      type: rest_api
      endpoint: https://api.example.com/customers
      resource: customers
    transform: |
      SELECT 
        customer_id,
        DATE_TRUNC('month', order_date) as month,
        SUM(amount) as monthly_revenue
      FROM {{ source }}
      GROUP BY customer_id, DATE_TRUNC('month', order_date)
    tests:
      - assert: "monthly_revenue > 0"
      - unique: [customer_id, month]

  4. Validates safety (blocks dangerous operations)

  5. Saves file if --apply is set

Generate and Save Automatically​

msh ai new --name customer_revenue --apply

Generates the asset and saves it automatically without prompting.

Generate and Save to Specific Path​

msh ai new --name customer_revenue --apply --path assets/customer_revenue.msh

Generates the asset and saves it to the specified path.

Description Examples​

REST API Ingestion​

Create an asset that ingests customer data from a REST API endpoint
https://api.example.com/customers and calculates total revenue per customer

SQL Database Ingestion​

Create an asset that reads from the orders table in PostgreSQL and
calculates monthly revenue grouped by customer and month

Transformation Only​

Create an asset that transforms the stg_orders staging table to calculate
monthly revenue per customer, joining with customer information

Safety Validation​

The safety layer blocks dangerous operations:

  • DROP TABLE
  • TRUNCATE TABLE
  • DELETE FROM
  • ALTER TABLE ... DROP COLUMN

If the generated asset contains dangerous operations, generation is blocked.

Prerequisites​

  1. AI Configuration: Must configure AI provider first

    msh config ai --provider openai --model gpt-4 --api-key env:OPENAI_API_KEY

  2. Manifest: Generate manifest before using AI commands

    msh manifest

  3. Project Context: AI uses project context (sources, glossary) to generate better assets

Refining Generated Assets​

After generation, you can:

  1. Review the asset: Check the generated code

    msh ai review assets/customer_revenue.msh

  2. Explain the asset: Understand what it does

    msh ai explain assets/customer_revenue.msh

  3. Fix issues: Let AI suggest fixes

    msh ai fix assets/customer_revenue.msh --apply

  4. Improve tests: Generate better tests

    msh ai tests assets/customer_revenue.msh --apply

Best Practices​

  • Be specific: Provide detailed descriptions for better results
  • Review before applying: Always review generated code before --apply
  • Use glossary terms: Reference glossary terms in descriptions for better alignment
  • Iterate: Use msh ai fix and msh ai review to refine generated assets