Database Commands

Holo-JS ships internal CLI commands through the @holo-js/cli package and its holo binary for the everyday database workflow: scaffolding files, running migrations, seeding data, and pruning models.

Inside a project, run direct Holo-JS commands through your package manager:

npx holo list

Equivalent forms:

• pnpm dlx holo ...
• yarn dlx holo ...
• npx holo ...

Use package scripts such as npm run dev and npm run build for framework lifecycle commands.

Use holo list to see every available command. The output groups Holo-JS's internal commands separately from app commands auto-discovered from server/commands.

Command discovery

npx holo list

Use this as the entry point when you want to see the installed internal commands and any custom commands your app provides.

Scaffolding commands

Create a model

npx holo make:model User
npx holo make:model courses/Course --migration --observer --factory --seeder

make:model creates files under:

• server/models
• server/db/observers
• server/db/factories
• server/db/seeders
• server/db/migrations

It also refreshes Holo-JS discovery output so runtime commands can see the generated model, seeder, and migration registries.

Create a migration

npx holo make:migration create_users_table
npx holo make:migration create_users_table --create users
npx holo make:migration add_status_to_users_table --table users

This creates a timestamped migration in server/db/migrations. holo dev and holo build keep the generated registries current; holo prepare is available when you only want to refresh discovery output.

Use:

• --create users
  • when the migration is creating a new table
• --table users
  • when the migration is changing an existing table

The generator can still infer common create, alter, and drop shapes from conventional file names, but the flags make the intended scaffold explicit.

Create cache tables

npx holo cache:table

Use this when your cache config uses the database driver. The generator creates a normal migration file under server/db/migrations for the cache entry and cache lock tables.

Create the media table

npx holo media:table

Use this when @holo-js/media was installed manually. npx holo install media already creates this migration.

Create a seeder

npx holo make:seeder RolesSeeder

This creates a seeder in server/db/seeders and refreshes generated discovery artifacts.

Create an observer

npx holo make:observer UserObserver
npx holo make:observer courses/CourseObserver

This creates an observer in server/db/observers. Standalone observer generation does not rewrite an existing model automatically. If you want the observer wired into a new model immediately, use make:model --observer.

Create a factory

npx holo make:factory UserFactory

This creates a factory in server/db/factories.

Runtime commands

Run migrations

npx holo migrate
npx holo migrate --step 1

Before running, the command rescans the configured migration directory and refreshes the generated registry, including migrations that were created manually.

Refresh the database from scratch

npx holo migrate:fresh
npx holo migrate:fresh --seed
npx holo migrate:fresh --seed --only roles,admin
npx holo migrate:fresh --seed --force

migrate:fresh drops every table in the active connection, reruns all registered migrations from scratch, and refreshes the internal generated schema metadata under .holo-js/generated at the end of the migration pass.

Use --seed when you want the fresh database to be reseeded immediately after migrations finish. The seeding flags match npx holo seed:

• --only roles,admin
• --quietly
• --force

Roll back migrations

npx holo migrate:rollback
npx holo migrate:rollback --batch 1
npx holo migrate:rollback --step 1

Run seeders

npx holo seed
npx holo seed --only database
npx holo seed --only roles,admin
npx holo seed --quietly
npx holo seed --force

seed runs the seeders discovered from server/db/seeders.

Prune models

npx holo prune
npx holo prune Session
npx holo prune Session AuditLog

prune works in two modes:

• with no arguments, it prunes every registered model that defines prunable
• with one or more model names, it prunes only that explicit set

If you name an unknown model, the command fails. If you name a registered model that does not define prunable, the command also fails. When no model names are passed and no registered models are prunable, the command succeeds and reports that there was nothing to prune.

Cache maintenance

npx holo cache:clear
npx holo cache:clear --driver redis
npx holo cache:forget dashboard.stats

Use these commands when you want to clear one configured store or drop one specific key without writing a custom script.

Interactive prompts

If a required argument is missing and the terminal session is interactive, Holo-JS prompts for it instead of failing immediately.

For example, this will ask for the model name:

npx holo make:model

Some generator commands also ask follow-up questions for optional scaffolding when that makes the workflow faster.

Disable prompts explicitly with:

npx holo make:model --no-interactive

In non-interactive environments, missing required values fail immediately.

Project discovery

Runtime commands read generated registries under .holo-js/generated to find:

• models
• migrations
• seeders
• commands
• discovery metadata

Generator commands refresh those artifacts when they can. holo dev and holo build also keep them current before starting the framework lifecycle command.

App commands

App commands are auto-discovered from server/commands without registration.

Example:

server/commands/courses/reindex.ts

import { defineCommand } from '@holo-js/cli'

export default defineCommand({
  description: 'Reindex course data.',
  async run() {
    console.log('courses reindexed')
  },
})

That file is available as:

npx holo courses:reindex

If the file does not provide an explicit name, the command name is derived from its path under server/commands.