@happyvertical/smrt-cli

Developer CLI for the s-m-r-t framework. Provides introspection, code generation, database management, and auto-generated CRUD commands for s-m-r-t objects.

Installation

pnpm add -D @happyvertical/smrt-cli

Commands

Introspection

| Command | Description | |---------|------------| | smrt introspect | Discover s-m-r-t objects in project and node_modules | | smrt introspect --verbose | Include detailed field information | | smrt objects | List all registered s-m-r-t objects | | smrt schema <object> | Show detailed schema for an object | | smrt status | Show system status (database, AI, registry) | | smrt doctor | Run the umbrella project-health diagnostics (aliases: check, diagnose) |

smrt doctor reports project-health and integration problems. Noun-scoped validators such as smrt db:validate retain their narrower contracts; do not use a generic smrt validate command as a second project-health entry point. Artifact consumers must still verify their own inputs and fail closed—running doctor is an observability aid, not a prerequisite for safe loading.

To inspect the same generation-snapshot contract used by the Vite plugins:

smrt doctor \
  --generation-snapshot .ci/smrt-generation-snapshot.json \
  --generation-snapshot-sha256 "$SMRT_GENERATION_SNAPSHOT_SHA256" \
  --generation-snapshot-provenance "$GITHUB_SHA" \
  --generation-snapshot-source-root "$GITHUB_WORKSPACE"

The four snapshot options are atomic: supplying any one requires all four.

Database

| Command | Description | |---------|------------| | smrt db:status | Show pending schema changes and classify failed migration history | | smrt db:migrate | Apply pending migrations | | smrt db:migrate --force-migration <exact-id> [--force-migration <exact-id>...] | Force one or more exact generated migrations in one atomic batch while preserving every other guard | | smrt db:migrate-uuid | Convert schema-declared UUID text columns to native PostgreSQL uuid after data has been remapped | | smrt db:diff | Show schema differences without generating migration files | | smrt db:rollback | Roll back the last migration by executing its recorded DOWN script; refuses when no DOWN script exists | | smrt db:rollback --mark-only | Record-only: mark migrations rolled back without running any DOWN script (schema untouched) | | smrt db:history | Show migration history with active-vs-superseded failure classification |

File-backed SQL/TypeScript migration generation is not supported. s-m-r-t schema migrations are manifest-driven; model schema with s-m-r-t objects and apply changes with smrt db:migrate.

Use --force-migration <exact-id> for a known checksum, failed, or interrupted migration that is safe to retry. Repeat the flag to recover multiple verified IDs in the same atomic invocation:

smrt db:migrate \
  --force-migration create_table_commissions \
  --force-migration create_table_referral_links

Each selector must be one exact generated migration ID. Comma-separated lists, wildcards, empty values, and combining exact selectors with global --force are rejected, as are IDs absent from the current generated migration batch. Duplicate exact IDs are normalized to one selection. Unrelated checksum, failed, and running records remain fail-closed even when the atomic batch reconciles live schema drift. Global --force remains available by itself for backward compatibility but intentionally overrides guards for the whole pending batch.

Audited PostgreSQL timestamp conversion

timestamp without time zone values do not carry enough information for s-m-r-t to infer their original instant. After auditing every historical writer, database default, trigger, and raw SQL path, an operator may confirm that the legacy values are UTC wall times and include the exact opt-in:

smrt db:migrate --postgres-timestamp-legacy-timezone UTC

The option has no default and rejects every value other than UTC. On PostgreSQL, db:migrate first converts framework-owned _smrt_* timestamp columns before migration-tracker bootstrap, then converts manifest-owned columns to timestamptz with USING column AT TIME ZONE 'UTC'. This preserves the proven UTC instants. It is not safe for a database with any local-time writer; use an application-owned, provenance-aware migration in that case. Rehearse against a restored clone and keep a verified backup because type upgrades have no automatic down migration. smrt db:diff --postgres-timestamp-legacy-timezone UTC previews manifest-owned changes; smrt db:migrate --dry-run --postgres-timestamp-legacy-timezone UTC also queries and prints the read-only _smrt_* conversion plan without initializing the tracker or writing to the database.

Code Generation

| Command | Description | |---------|------------| | smrt generate-mcp | Generate MCP server from registered objects (aliases: generate-mcp-server, mcp) | | smrt generate-types | Generate TypeScript declarations from manifest (alias: generate-declarations) | | smrt generate-routes | Generate SvelteKit API routes (aliases: routes, generate:routes) | | smrt generate-register | Generate .smrt/register.js from discovered packages (aliases: register, generate:register) |

Generation commands are hyphenated. generate-routes and generate-register also answer to a colon alias for backward compatibility; generate-mcp and generate-types do not.

smrt generate-mcp writes .smrt/mcp-server/index.js by default and emits JavaScript for a .js target, so node .smrt/mcp-server/index.js runs it directly. Ask for a .ts target to keep the annotated TypeScript for tsx or Node's type stripping:

smrt generate-mcp --output-path .smrt/mcp-server/index.ts

The generated server is always an ES module, so a .cjs/.cts output path is rejected. It imports @modelcontextprotocol/server, @happyvertical/smrt-core, and @happyvertical/smrt-config at runtime (plus @happyvertical/smrt-jobs for task actions and @happyvertical/smrt-tenancy for tenant-scoped objects), so those have to be resolvable from the project you run it in — under pnpm's strict layout that means declaring them, not relying on the CLI's own dependencies.

Documentation

| Command | Description | |---------|------------| | smrt docs:agents | Generate .agents/smrt-framework.md for consumer projects | | smrt docs:claude | Deprecated compatibility alias for .claude/smrt-framework.md | | smrt dev:knowledge-index --format markdown\|json | Print the deterministic s-m-r-t + SDK knowledge index | | smrt dev:knowledge-check --format markdown\|json | Check agent knowledge freshness | | smrt dev:knowledge-diff --format markdown\|json | Show changed files and affected package experts | | smrt knowledge:review-context --scope project\|local\|package\|sdk\|installed --package <name> --format markdown\|json | Build a model-ready domain review prompt bundle | | smrt knowledge:architecture-context --scope project\|local\|package\|sdk\|installed --package <name> --format markdown\|json | Build a model-ready domain architecture prompt bundle |

Configuration

| Command | Description | |---------|------------| | smrt config:export | Export agent config for SSG | | smrt export | Export data in various formats | | smrt init | Initialize a new s-m-r-t project |

Dispatch

| Command | Description | |---------|------------| | smrt dispatch:list | List dispatch messages | | smrt dispatch:process | Process pending dispatches | | smrt dispatch:retry | Retry failed dispatches | | smrt dispatch:cleanup | Clean up old dispatch records |

Git Integration

| Command | Description | |---------|------------| | smrt git:init | Configure JSON-aware merge driver for data files | | smrt merge-json <base> <ours> <theirs> | Manual JSON merge (called by git automatically) |

Scaffolding

| Command | Description | |---------|------------| | smrt gnode create <name> | Create new gnode from template | | smrt gnode list-templates | Show available templates | | smrt playground init | Scaffold package or app playground modules | | smrt playground dev | Run the shared or local playground host | | smrt playground list | List discovered playground entries and modes |

Playground

| Command | Description | |---------|------------| | smrt playground init | Scaffold package or app playground files | | smrt playground dev | Run the shared workspace host or local app playground | | smrt playground list | Show discovered playground modules and preview entries |

Auto-Generated Object Commands

For each registered s-m-r-t object, the CLI generates:

| Pattern | Description | |---------|------------| | <object>:list | List objects with filtering and pagination | | <object>:get <id> | Get object by ID or slug | | <object>:create | Create new object (interactive) | | <object>:update <id> | Update existing object | | <object>:delete <id> | Delete object | | <object>:<method> <id> | Custom methods exposed via cli: { include: [...] } |

Custom methods on s-m-r-t objects are auto-discovered from manifests. Method parameters become CLI options (camelCase to kebab-case).

Usage

# Discover what s-m-r-t objects are available
smrt introspect

# Generate an MCP server
smrt generate-mcp

# Scaffold a package playground definition
smrt playground init

# Inspect discovered playground entries
smrt playground list

# Run a custom method on an object
smrt agent:research abc123 --query "AI safety"

# Generate agent context for downstream projects
smrt docs:agents

# Deprecated compatibility alias for Claude Code output
smrt docs:claude

# Check deterministic agent knowledge freshness
smrt dev:knowledge-check --changed --strict --format markdown
smrt dev:knowledge-check --strict --format json

# Build downstream domain context for local/manual model review
smrt knowledge:review-context --scope package --package content --format markdown
smrt knowledge:architecture-context "tenant-aware publishing workflow" --format json

# Inspect discovered package playground modules
smrt playground list

UI Surfaces

The CLI treats UI surfaces as three separate contracts:

• ./svelte for reusable components
• ./playground for preview metadata consumed by smrt playground
• package-local page shells when a package needs its own dev pages

For this release, packages only need ./svelte and ./playground as public UI contracts. Package-local page shells can exist for dev workflows without becoming a published package standard.

See docs/ui-surfaces.md for the full convention.

Configuration

The CLI uses @happyvertical/smrt-config (cosmiconfig). Configuration is optional -- sensible defaults apply.

// smrt.config.js
export default {
  packages: {
    cli: {
      entryPoint: './dist/index.js',  // default: auto-detect from package.json
      database: {
        type: 'sqlite',               // 'sqlite' | 'postgres'
        url: './data.db'              // default: ':memory:'
      },
      format: 'table',                // 'table' | 'json' | 'yaml' | 'plain'
    }
  }
};

Entry Point Discovery

The CLI loads s-m-r-t objects from your project entry point:

1. Explicit entryPoint in config
2. package.json exports ['.'].import or ['.']
3. package.json main field
4. Fallback: ./dist/index.js

Manifest Discovery

The CLI auto-discovers s-m-r-t manifests from:

• Project root: dist/manifest.json, dist/static-manifest.js, .smrt/manifest.json, and other standard locations
• Installed packages: scans node_modules/@happyvertical/smrt-* for manifest files

If compiled classes cannot be loaded, the CLI falls back to manifest-only mode (introspection and code generation work, but CRUD and custom methods do not).

Dependencies

• @happyvertical/smrt-core -- ORM, manifest, code generation
• @happyvertical/smrt-config -- configuration loading
• @happyvertical/smrt-scanner -- AST scanning for metadata extraction