@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

For package validation, pnpm --filter @happyvertical/smrt-cli typecheck checks both CLI source and all src/**/*.test.ts / src/**/*.spec.ts fixtures. The test project uses the repository's test-only TypeScript settings in tsconfig.test.json; production declarations remain under tsconfig.typecheck.json.

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:migrate-int8	Widen legacy pre-#2373 int4 columns to BIGINT after reviewing the maintenance-window preflight
smrt db:migrate-ledger-accounts [--dry-run]	Move smrt-ledgers accounts out of the pre-#3098 shared accounts table into ledger_accounts (PostgreSQL; run between two db:migrate passes — see the smrt-ledgers README)
smrt db:migrate-qualified-names [--dry-run] [--tenant <id>] [--force]	Rewrite stored deprecated qualified names (@smrt({ previousQualifiedNames })) to current names. Opt-in, idempotent, tracked in _smrt_backfills; smrt doctor --db counts what remains (#3338)
smrt db:drop-framework-base-tables	One-time removal of the five framework-base tables (smrt_objects, smrt_classes, smrt_collections, smrt_hierarchicals, smrt_polymorphic_associations) orphaned by #2644; refuses if any target table has rows, an unexpected shape, or an inbound foreign key
smrt db:drop-framework-base-tables --dry-run	Print the drop plan (tables and companion indexes) without executing
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
smrt db:permissions --dry-run	Plan the declared PostgreSQL role permission contract
smrt db:permissions --apply --expected-fingerprint <hash>	Explicitly apply a reviewed permission plan
smrt db:validate	Validate configured PostgreSQL permissions or JSON database integrity

For separate migration-owner, runtime, and monitoring roles, see the PostgreSQL permissions guide. doctor --db includes read-only permission diagnostics when configured.

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.

Empty text blocks those conversions too: '' (or whitespace) is not a timestamp, JSON document, or integer. When the manifest and live columns are both nullable, opt in to storing it as NULL:

smrt db:diff --empty-text-as-null      # preview; notes how many values become NULL
smrt db:migrate --empty-text-as-null

It covers text -> timestamptz, jsonb and integer conversions. Any other value that does not convert still blocks, and NOT NULL columns are never changed. For timestamptz and jsonb the diff probes the column first: without the flag the blocking advisory names the empty-text count. text -> integer is not probed at diff time: the conversion is listed as executable (with the note "empty-text value(s), if any, become NULL" under the flag), and a value that is not an integer only fails when db:migrate applies it, rolling the batch back. db:status and db:history take the same flag, so they assess the same convergence. Separately, --postgres-timestamp-legacy-timezone=UTC converts a legacy text timestamp with NULLIF(…, '') / 'null' → NULL even without --empty-text-as-null (a NOT NULL column still fails at ALTER time).

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

docs:agents includes package AGENTS guidance and lists linked module files by source path; it does not read or embed their bodies. Use smrt docs:agents --complete for a complete authored reference. The deprecated docs:claude alias supports the same flag and retains its historical output path. Regenerate snapshots after moving the project or updating dependencies so the local source paths remain current.

docs:agents also installs the smrt-catalog agent skill into .claude/skills/ and .agents/skills/ so an agent consults the knowledge catalog before hand-rolling infrastructure. Pass --no-install-skills to skip it. A copy you edited (the generated marker removed) is never overwritten.

Review and architecture prompt bundles include package guidance and modules matched by file or focus hints. Add --complete to either context command to include every module for the selected packages. These commands still build the knowledge index; documentation snapshots use lightweight package discovery.

Configuration

Command	Description
smrt config:export	Export agent config for SSG
smrt export	Export data in various formats
smrt init	Initialize s-m-r-t in an existing SvelteKit project
smrt cookbook validate <file|url>	Check a cookbook against cookbook/v1 and the recipe manifests
smrt cookbook apply <file|url> [dir]	Create a project from a cookbook and the smrt-start template, its smrt packages pinned to this CLI's release (--into, --template, --dry-run, --no-install)
smrt kitchen [dir]	Serve the planner on localhost, chat to a cookbook, Send to kitchen applies it into dir (--planner, --template, --no-open, --no-install)
smrt kitchen apply <url|file> [dir]	cookbook apply that also takes a plan URL

smrt export reads the export section of smrt.config.js. A listed type that is not registered fails the command (non-zero exit, naming the type) instead of skipping the file. A file listing several types that share one table (STI) exports the union of their columns (absent columns are NULL; _meta_type distinguishes rows); set fields: 'common' on the file to keep only the columns every type has. A column marked exported: false for any listed type is never emitted for that type's rows, even when another listed type exports it: the value is NULLed per row from the _meta_type discriminator (the export selects it even when _meta_type is not an output column). If a row's type cannot be matched to a listed type, or an excluding type has no discriminator, the export fails naming the field and types rather than publishing the column. include whitelists cannot re-enable an exported: false field.

smrt init updates an existing SvelteKit application's package.json with the direct dependencies its generated source and default MCP server require: @happyvertical/smrt-core, @happyvertical/smrt-config, and @modelcontextprotocol/server. It also adds @happyvertical/smrt-cli as a development dependency so the generated project can run smrt generate-mcp. Run the project's package-manager install command after initialization. Existing versions are preserved; s-m-r-t workspace projects receive workspace:* ranges and consumer projects receive the CLI's published release line.

The generated src/lib/server/smrt.ts exports only runtime (classOptions() and getCollection() over DATABASE_URL/DATABASE_TYPE), which generated API routes call per request; it no longer exports the deprecated getCollection/getSmrtConfig accessors. To adopt the full application runtime, replace that object with createSmrtSvelteKitRuntime() from @happyvertical/smrt-app-runtime/sveltekit and mount its handle/init.

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

Application operations (smrt app)

Operational commands for a generated s-m-r-t application, run from the application root. They replace the template's copied scripts/*.mjs, so an app's package.json scripts are one-liners:

{
  "dev": "smrt app dev",
  "build": "smrt app build",
  "preview": "smrt app start",
  "db:migrate": "vite build && smrt app migrate",
  "app:setup": "smrt app setup",
  "app:doctor": "smrt app doctor",
  "worker": "smrt app worker task",
  "worker:schedule": "smrt app worker schedule"
}

Command	Description
smrt app install	Local: setup, start, and open owner onboarding under one operation lock
smrt app setup	Build, run smrt db:migrate explicitly, and prepare the private owner-onboarding handoff
smrt app recover	Local: rotate the single-use owner onboarding invitation
smrt app start / stop	Local: run the production build on loopback; readiness is proven by app id, process instance, and configuration fingerprint
smrt app doctor	Secret-free findings (invalid-runtime-profile, unsafe-local-bind, runtime-path-unavailable, migration-required, …); exits 1 on any error (default operation)
smrt app open	Open the app, or the pending onboarding launch file
smrt app backup [destination]	Local: copy the validated data root to a new private directory outside the checkout
smrt app export [path] / import <path>	Logical, asset-aware bundle; import requires an empty target (deployed: SMRT_MAINTENANCE_MODE=true)
smrt app migrate	Establish local storage custody, then smrt db:migrate, under the operation lock
smrt app worker [task|schedule]	Deployed: imports .smrt/runtime/register.js, then runs the jobs runner until SIGTERM. The kind defaults to task; any other value is a usage error before anything starts
smrt app dev|build|vite [args]	Run the app's installed Vite with .env loaded (shell wins); build validates ./mcp-apps first

Success output is JSON on stdout; a failure is one JSON envelope on stderr with exit code 1 and never contains secret values. The same primitives (operation lock, writer lease, state root, artifact-path custody, portability) are importable without side effects from @happyvertical/smrt-cli/app. Contract details: agents/app-commands.md.

On macOS, /tmp commonly links to /private/tmp. Local setup rejects symbolic links in state/data path components and reports the rejected component. For an isolated trial home, first inspect and trust the intended directory, then select its canonical spelling explicitly, for example HOME=/private/tmp/my-owned-trial-home pnpm app:setup. Use that same home for later app commands and the running app. Select a canonical SMRT_DATA_DIR too if overriding data storage. The directories must still meet ownership, permissions, and source-tree separation checks; resolving a link is not proof that its target is trusted. The runtime never automatically trusts symlinks.

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: [...] }

create and update apply the same write policy as the generated REST routes and MCP tools in every input mode (--from-file, interactive, flags): fields outside api.writable, readonly fields and server-managed keys (id, tenantId, timestamps) are dropped.

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'
    }
  }
};

Database precedence

Every db:* command resolves its database once, at startup:

1. packages.cli.database.url from any config layer — an explicit project setting always wins, so a stray shell DATABASE_URL never retargets it.
2. DATABASE_URL, with the engine from the config's database.type, else DATABASE_TYPE (sqlite | postgres), else the URL scheme (postgres:// / postgresql:// → postgres, anything else sqlite). An unsupported DATABASE_TYPE disables this step with a warning.
3. The :memory: default, which schema commands refuse.

smrt app setup and smrt app migrate hand smrt db:migrate the profile's database through step 2, so an application does not forward DATABASE_URL in its own config. The rule is smrt-config's resolveCliDatabaseConfig(), which smrt-dev-mcp uses too.

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-app-runtime -- local storage custody and runtime composition for smrt app
• @happyvertical/smrt-scanner -- AST scanning for metadata extraction