Fragno CLI

The Fragno CLI (@fragno-dev/cli) provides command-line tools for working with Fragno. It can serve Fragments locally for development and manage database-enabled Fragments — including schema outputs, migration generation, database version tracking, and migration execution.

Installation

The CLI is typically installed as a development dependency:

npm install --save-dev @fragno-dev/cli

# Or use directly with npx
npx @fragno-dev/cli --help

Commands

serve

Start a local HTTP server to serve one or more Fragno Fragments. The target files must export instantiated Fragments (i.e. the return value of a create*() factory function). When multiple fragments are provided, each is mounted on its own route prefix.

Usage:

npx fragno-cli serve <fragment-file> [fragment-file...] [options]

Arguments:

• <fragment-file> - Path to a file that exports one or more instantiated Fragments

Options:

• --port, -p - Port to listen on (default: 8080)
• --host, -H - Host to bind to (default: localhost)

Examples:

# Serve a single fragment
npx fragno-cli serve lib/my-fragment.ts

# Serve on a custom port
npx fragno-cli serve lib/my-fragment.ts --port 3000

# Serve multiple fragments
npx fragno-cli serve lib/auth-fragment.ts lib/comment-fragment.ts

Output:

  Found 1 fragment(s) in lib/my-fragment.ts: example-fragment

Fragno server is running on: http://localhost:8080

Fragment: example-fragment
  Mount: http://localhost:8080/api/example-fragment
  Routes:
    GET /api/example-fragment/hash
    GET /api/example-fragment/data
    POST /api/example-fragment/sample

Unmatched requests return a 404 JSON response listing the available mount routes.

db generate

Generate SQL migrations or schema outputs. The output format is explicit and selected with --format.

Usage:

npx fragno-cli db generate <path-to-fragment-instance> [options]

Arguments:

• <path-to-fragment-instance> - Path to a file that exports an instantiated Fragment or FragnoDatabase instance

Options:

• --format - Output format: sql (migrations, default), drizzle (schema), or prisma (schema)
• --output, -o - Output path for the generated file (can be a file path or directory). Defaults to the current directory. SQL migrations use date-prefixed filenames; Drizzle defaults to fragno-schema.ts, Prisma defaults to fragno.prisma
• --from, -f - Source version to generate migration from (default: current database version for SQL output)
• --to, -t - Target version to generate migration to (default: latest schema version)
• --prefix, -p - String to prepend to the generated file (e.g., /* eslint-disable */)

Note: from and to are only supported for --format sql.

Examples:

# Generate SQL migrations (default output)
npx fragno-cli db generate lib/comment-fragment-server.ts

# Generate SQL migrations to specific file
npx fragno-cli db generate lib/comment-fragment-server.ts --output migrations/001.sql

# Generate migration between specific versions
npx fragno-cli db generate lib/comment-fragment-server.ts --from 1 --to 3 --output migrations/v1-to-v3.sql

# Generate a Drizzle schema module
npx fragno-cli db generate lib/comment-fragment-server.ts --format drizzle --output schema/fragno-schema.ts

# Generate a Prisma models-only schema
npx fragno-cli db generate lib/comment-fragment-server.ts --format prisma --output prisma/schema/fragno.prisma

# Generate with linter disable comment
npx fragno-cli db generate lib/comment-fragment-server.ts --prefix "/* eslint-disable */"

What it does:

For --format sql, this command connects to your database and reads the current schema version. It then generates migrations. If --from and --to are provided, it generates a migration from the source version to the target version. If --from is not provided, it generates a migration to the latest version.

For --format drizzle or --format prisma, no database connection is required. The CLI emits a schema artifact based on your Fragment schemas.

Output:

Loading target file: /path/to/lib/comment-fragment-server.ts
Found FragnoDatabase instance: fragmentDb
Generating SQL migrations...
✓ Generated: /path/to/20250202_001_f001_t003_comment-fragment.sql

✓ Output generated successfully!
  Files generated: 1
  Fragments:
    - comment-fragment (version 3)

db migrate

Apply migrations to your database, bringing it to the target schema version.

Note: this is only supported for SQL migrations (--format sql). For Drizzle or Prisma workflows, use db generate --format drizzle or db generate --format prisma and apply changes with your ORM's tooling (for example drizzle-kit or prisma migrate).

Usage:

npx fragno-cli db migrate <path-to-fragment-instance> [options]

Arguments:

• <path-to-fragment-instance> - Path to a file that exports an instantiated Fragment or FragnoDatabase instance

Options:

• --to, -t - Target version to migrate to (default: latest schema version)
• --from, -f - Expected current database version (validates before migrating). If the current version doesn't match, the command will fail with an error

Examples:

# Migrate to latest version
npx fragno-cli db migrate lib/comment-fragment-server.ts

# Migrate to specific version
npx fragno-cli db migrate lib/comment-fragment-server.ts --to 5

# Validate current version before migrating
npx fragno-cli db migrate lib/comment-fragment-server.ts --from 3 --to 5

What it does:

Migrates the database to the target version. If --from is provided, it validates that the current version matches the expected version. If --to is not provided, it migrates to the latest version.

Output:

Loading target file: /path/to/lib/comment-fragment-server.ts
Found FragnoDatabase instance: fragmentDb
Migrating database for namespace: comment-fragment
Migrating to version 5...
Current version: 3
✓ Migration completed successfully
  Namespace: comment-fragment
  New version: 5

If the database is already at the target version:

Loading target file: /path/to/lib/comment-fragment-server.ts
Found FragnoDatabase instance: fragmentDb
Migrating database for namespace: comment-fragment
Migrating to latest version (5)...
✓ Database is already at the target version. No migrations needed.

db info

Display information about the current database and schema state.

Usage:

npx fragno-cli db info <path-to-fragment-instance>

Arguments:

• <path-to-fragment-instance> - Path to a file that exports an instantiated Fragment or FragnoDatabase instance

Example:

npx fragno-cli db info lib/comment-fragment-server.ts

What it does:

This command shows you the current status of the database and schema.

search

Search the Fragno documentation directly from the command line. Results are grouped by page, showing all relevant sections found on each page.

Usage:

npx fragno-cli search <query> [options]

Arguments:

• <query> - Search query (can be multiple words)

Options:

• --limit - Maximum number of results to show (default: 10)
• --json - Output results in JSON format instead of markdown
• --base-url - Base URL for the documentation site (default: fragno.dev)

Examples:

npx fragno-cli search db

npx fragno-cli search "getting started" --limit 5 --json