Fragno CLI
Command-line tools for managing Fragno database fragments
The Fragno CLI (@fragno-dev/cli) provides command-line tools for working with Fragno. It is used
to manage database-enabled Fragments. It handles schema 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 --helpDatabase Fragments Only
The CLI is only required when working with Fragments that include a database layer. Standard Fragments without database integration don't require the CLI.
Commands
db generate
Generate a schema file for database setup or migrations. The type of generated file is determined by the database adapter used.
- For SQL-based adapters (Kysely), the generated file is a SQL migration file.
- For schema generator adapters (Drizzle), the generated file is a TypeScript schema file.
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:
--output,-o- Output path for the generated file (can be a file path or directory). Defaults toschema.sqlfor SQL-based adapters,schema.tsfor Drizzle--from,-f- Source version to generate migration from (default: current database version for SQL adapters)--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 in Kysely migrations.
Examples:
# Generate schema for latest version (default output)
npx fragno-cli db generate lib/comment-fragment-server.ts
# Generate schema 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 with linter disable comment
npx fragno-cli db generate lib/comment-fragment-server.ts --prefix "/* eslint-disable */"What it does:
This command connects to your database and reads the current schema version in the database. It then
generates a migration. 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.
Output:
Loading target file: /path/to/lib/comment-fragment-server.ts
Found FragnoDatabase instance: fragmentDb
Generating schema for namespace: comment-fragment (from version 1 to version 3)
✓ Schema generated successfully: schema.sql
Namespace: comment-fragment
Schema version: 3db migrate
Apply migrations to your database, bringing it to the target schema version.
Note: this is not supported in Drizzle. In Drizzle, you can use the generate command to
generate a schema file and then use the drizzle-kit push command to apply the schema to your
database. Make sure to update your drizzle.config.ts file to point to the generated schema file in
addition to your own database schema.
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 5What 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: 5If 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.Adapter Support Required
Not all database adapters support running migrations directly. Some adapters (like certain Drizzle
configurations) only support schema generation. If your adapter doesn't support migrations, you'll
receive an error message suggesting to use db generate instead.
Idempotent and Safe
Migrations are idempotent - running db migrate multiple times is safe. If the database is
already at the target version, no changes will be made. Use --from to add extra safety by
validating the current version before applying changes.
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.tsWhat 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