npm package: @ortha/cli
Description: Command-line tool for Ortha database management and admin operations — provides commands for running migrations, seeds, generating migration files, creating admin users, and introspecting the database schema.
Latest version: 0.0.4

# @ortha/cli

Command-line tool for Ortha database management and admin operations — provides commands for running migrations, seeds, generating migration files, creating admin users, and introspecting the database schema.

## Installation

Link the CLI globally from the monorepo root:

```bash
npm run link:cli
```

To unlink:

```bash
npm run unlink:cli
```

## Commands

### Database Migrations

```bash
# Run all pending migrations
ortha migrations:run

# Generate a new migration file from schema diff
ortha migrations:generate --name <migration-name>
```

### Database Seeds

```bash
# Run all seed files
ortha seeds:run

# Generate a new seed file
ortha seeds:generate --name <seed-name>
```

### Admin User Creation

```bash
# Create the initial root admin user
ortha admin:create
```

The command prompts for `email`, `password`, and `full name`, hashes the password with bcrypt (12 salt rounds), and saves the user as active with the `admin` role.

**Prerequisites:**

- Run migrations first (`ortha migrations:run`)
- Run seeds first (`ortha seeds:run`) so the `admin` role exists

**Behavior:**

- If an `admin` user already exists, the command fails immediately — root admin creation is one-time only
- If the `admin` role is missing, the command fails with guidance to run seeds
- If the email already exists, the command fails without changing the existing user

### Schema Introspection

```bash
# Introspect the live database schema
ortha db:introspect
```

## API Reference

The package exports types only (no runtime functions):

| Export                     | Kind | Description                            |
| -------------------------- | ---- | -------------------------------------- |
| `ServerConfig`             | type | Server configuration shape             |
| `DatabaseConnectionConfig` | type | Database connection parameters         |
| `SchemaDefinition`         | type | Sequelize schema definition            |
| `ModelRegistry`            | type | Map of model names to Sequelize models |
| `ColumnState`              | type | Column state for schema diffing        |
| `TableState`               | type | Table state for schema diffing         |
| `DiffOperation`            | type | Schema diff operation descriptor       |

## Internal Structure

```
src/lib/
├── bin/index.ts                    # Commander CLI entry point
├── types/index.ts                  # Type definitions
├── createAdmin/index.ts            # Admin user creation
├── runMigrations/index.ts          # Migration runner
├── runSeeds/index.ts               # Seed runner
├── generateMigration/index.ts      # Migration file generator
├── generateSeed/index.ts           # Seed file generator
├── diffState/index.ts              # Schema diff computation
├── extractModelState/index.ts      # Extract current model state
├── introspectDb/index.ts           # Live database introspection
├── loadConfig/index.ts             # Configuration loader
├── loadSchemas/index.ts            # Schema loader
└── promptAdminCredentials/index.ts # Interactive credential prompts
```

## Key Patterns

- Built with [Commander.js](https://github.com/tj/commander.js/) for CLI argument parsing.
- Schema diffing compares the current Sequelize model state against the live database to generate migrations.
- `loadConfig()` reads the server configuration to connect to the database.
- `loadSchemas()` dynamically imports all domain schemas for migration generation.
- Interactive prompts use `inquirer` for admin credential input.

## Building

```bash
nx build cli
```