Skip to main content

Commands Reference

@xond/api provides a CLI tool (xond-api) with several commands for managing your database and generating code.

Available Commands​

Commands can be run in two ways:

  1. Direct CLI: npx xond-api <command> or pnpm --filter your-api-app xond-api <command>
  2. PNPM Scripts: Most apps define convenient pnpm scripts that wrap the CLI commands

Using PNPM Scripts​

Most backend applications define pnpm scripts in their package.json:

{
  "scripts": {
    "xond:check": "npx xond-api check",
    "xond:create": "npx xond-api create",
    "xond:update": "npx xond-api update",
    "xond:generate": "npx xond-api generate",
    "xond:insert": "npx xond-api insert",
    "xond:shorten": "npx xond-api shorten"
  }
}

Then you can run:

pnpm xond:check
pnpm xond:create
pnpm xond:update
pnpm xond:generate
pnpm xond:insert

This documentation shows both the direct CLI commands and mentions the pnpm script equivalents where applicable.

xond-api check​

Validates your environment and database configuration.

# Direct CLI
pnpm --filter your-api-app xond-api check
pnpm --filter your-api-app xond-api check --verbose

# Or using pnpm script (if defined in package.json)
pnpm xond:check
pnpm xond:check --verbose

What it checks:

  • Environment is set to development or dev
  • Prisma is installed and initialized
  • DATABASE_URL is configured
  • Database type matches Prisma schema provider
  • Database is accessible and live

Example output:

ℹ️  Checking..
✅ Environment is set to development
✅ Prisma is installed
✅ Prisma is initialized
ℹ️  Detected database URL: postgresql://user:pass@localhost:5432/mydb
✅ Detected database type: postgresql
✅ The schema.prisma and DATABASE_URL is valid: postgresql
✅ Database name matches: mydb
✅ Database is live and accessible

xond-api create​

Creates the database structure by executing prisma/structure.sql.

# Direct CLI
pnpm --filter your-api-app xond-api create
pnpm --filter your-api-app xond-api create --verbose

# Or using pnpm script
pnpm xond:create
pnpm xond:create --verbose

What it does:

  • Reads the SQL file specified in DATABASE_STRUCTURE_FILE environment variable
  • Connects to your database
  • Executes the SQL statements
  • Supports PostgreSQL, MySQL, and SQL Server

Requirements:

  • .env file with DATABASE_URL and DATABASE_STRUCTURE_FILE
  • File path in DATABASE_STRUCTURE_FILE exists and is accessible
  • Database server is accessible

Example output:

🚀 Starting database creation...
🔄 Connecting to database (postgresql)...
✅ Database structure created successfully.

xond-api update​

Applies versioned database update scripts from prisma/update-struct-*.sql.

# Direct CLI
pnpm --filter your-api-app xond-api update
pnpm --filter your-api-app xond-api update --verbose

# Or using pnpm script
pnpm xond:update
pnpm xond:update --verbose

What it does:

  • Reads the directory path from DATABASE_UPDATE_FILE environment variable
  • Finds all update-struct-*.sql files in that directory
  • Sorts them by version number (semantic versioning)
  • Executes them in order against your database

Requirements:

  • .env file with DATABASE_URL and DATABASE_UPDATE_FILE
  • DATABASE_UPDATE_FILE points to a directory containing update SQL files
  • Files follow naming convention: update-struct-<version>.sql

File naming convention:

  • update-struct-1.0.0.sql
  • update-struct-1.1.0.sql
  • update-struct-2.0.0.sql

Example output:

🚀 Applying database update scripts...
🔄 Executing update 1.0.0 (prisma/update-struct-1.0.0.sql)
✅ Update 1.0.0 applied.
🔄 Executing update 1.1.0 (prisma/update-struct-1.1.0.sql)
✅ Update 1.1.0 applied.
🎉 All update scripts executed successfully.

xond-api generate​

Generates REST services, controllers, and frontend models from your Prisma schema.

# Direct CLI
pnpm --filter your-api-app xond-api generate
pnpm --filter your-api-app xond-api generate --verbose

# Or using pnpm script
pnpm xond:generate
pnpm xond:generate --verbose

What it generates:

  1. Backend Services (src/modules/json/services/generated/)

    • *Service.ts – REST service implementations for each model
    • serviceRegistry.ts – Registry of all services
    • fieldTypeMap.ts – Type mapping for form generation

  2. Frontend Models (src/generated/models/ in UI app)

    • *Model.tsx – TypeScript models with column definitions
    • index.ts – Exports and model registry

  3. Schema Files (prisma/)

    • schema.ts – JSON representation of your Prisma schema

Naming Convention Conversion:

The generate command automatically converts snake_case (from database/Prisma schema) to CamelCase (for generated code):

  • Model names: user_table → UserTable
  • Field labels: first_name → First Name
  • Field headers: created_at → Created At
  • TypeScript types: All generated types use CamelCase

This ensures:

  • Database remains in snake_case (standard convention)
  • Generated code uses familiar CamelCase conventions
  • Type safety from database to frontend

Requirements:

  • prisma/schema.prisma exists and is valid
  • Prisma client is generated (prisma generate)

Example output:

ℹ️  Generating..
✅ Generated JSON service for User
✅ Generated JSON service for Product
✅ Generated frontend model User
✅ Generated frontend model Product
✅ Generated static service registry: .../serviceRegistry.ts
✅ Generated schema.ts file: .../schema.ts
✅ Generated index.ts with imports and ColumnModelMap: .../index.ts
✅ Generated fieldTypeMap file for models: .../fieldTypeMap.ts

xond-api insert​

Generates and executes dummy data loaders from an Excel file.

# Direct CLI
pnpm --filter your-api-app xond-api insert
pnpm --filter your-api-app xond-api insert --verbose

# Or using pnpm script
pnpm xond:insert
pnpm xond:insert --verbose

What it does:

  1. Reads the Excel file specified in DATABASE_DUMMY_FILE environment variable
  2. Generates JavaScript loader files in prisma/dummy/ (one per table)
  3. Creates prisma/dummy/refillDatabase.js
  4. Executes the loaders to insert data into your database

Excel file format:

  • Each worksheet = one table
  • First row = column headers (must match Prisma model fields)
  • Subsequent rows = data rows
  • First column should contain primary key values

Requirements:

  • .env file with DATABASE_URL and DATABASE_DUMMY_FILE
  • File path in DATABASE_DUMMY_FILE exists and is accessible
  • prisma/schema.prisma exists
  • Database is accessible

Example output:

ℹ️  Inserting dummy data from Excel...
📁 Created missing directory: prisma/dummy
➡️  Processing table: users
➡️  Processing table: products
✅ Dummy data files and refillDatabase script generated successfully.
✅ Insert scripts executed successfully.

xond-api shorten​

Shortens relation names in your Prisma schema to avoid naming conflicts.

# Direct CLI
pnpm --filter your-api-app xond-api shorten
pnpm --filter your-api-app xond-api shorten --verbose

# Or using pnpm script
pnpm xond:shorten
pnpm xond:shorten --verbose

What it does:

  • Reads prisma/schema.prisma
  • Shortens long relation names that might cause Prisma errors
  • Simplifies relation field names (e.g., veryLongRelationNameToAnotherTable → parentToTable)
  • Updates the schema file in place

When to use:

  • After reverse engineering a database with very long table/column names
  • If you encounter Prisma relation name length errors
  • Before running xond-api generate if you have complex relations

Example:

Before:

model User {
  veryLongRelationNameToAnotherTable Table @relation("veryLongRelationNameToAnotherTable", ...)
}

After:

model User {
  parentToTable Table @relation("veryLongRelationNameToAnotherTable", ...)
}

Note: The relation name in @relation() stays the same (for database compatibility), but the field name is shortened.

Command Workflow Example​

Here's a typical workflow combining multiple commands:

# Using pnpm scripts (recommended)
# 1. Check environment
pnpm xond:check

# 2. Create database structure
pnpm xond:create

# 3. Reverse engineer Prisma schema (yields snake_case)
pnpm prisma:reverse
pnpm prisma:format

# 4. Shorten relation names if needed (optional)
pnpm xond:shorten

# 5. Generate Prisma client
pnpm prisma:generate

# 6. Generate code (converts snake_case to CamelCase)
pnpm xond:generate

# 7. Insert dummy data
pnpm xond:insert

# Or using direct CLI commands:
# pnpm --filter icbs-api xond-api check
# pnpm --filter icbs-api xond-api create
# pnpm --filter icbs-api prisma db pull
# pnpm --filter icbs-api prisma format
# pnpm --filter icbs-api prisma generate
# pnpm --filter icbs-api xond-api generate
# pnpm --filter icbs-api xond-api insert

Many apps also define convenient combined scripts:

# Regenerate everything (check → create → reverse → generate → insert)
pnpm regen:all

# Regenerate code only (after schema changes)
pnpm regen

# Re-insert dummy data
pnpm reinsert

Troubleshooting​

Command not found​

If xond-api command is not recognized, ensure:

  • @xond/api is installed in your project
  • You're running the command from the correct directory
  • Using pnpm --filter to target the correct workspace

Database connection errors​

  • Verify DATABASE_URL in .env is correct
  • Ensure database server is running
  • Check network/firewall settings
  • Verify credentials are correct

Prisma errors​

  • Run prisma generate before xond-api generate
  • Ensure prisma/schema.prisma is valid
  • Check that Prisma provider matches your database type