Tooling CLI reference

The tooling is a library of declarative commands that runs inside the Kiwi shell. After kiwi register <folder>, run each command as kiwi orm <command>, for example kiwi orm scaffold --connection .... The migration commands are hyphenated, such as kiwi orm model-apply.

Provider values (--provider, -db): sqlserver, postgresql, mysql, mariadb, oracle, sqlite, firebird, db2, saphana, informix, msaccess.

Data-first: database to code#

scaffold#

Read a live database schema and write kiwi-schema.json for review and customisation.

• --connection, -c (required): database connection string.
• --provider, -db (required): database provider.
• --schema-filter, -s: limit to one schema or owner (dbo, public, HR). Omit to read all non-system schemas.
• --output, -o: output path (default kiwi-schema.json).
• --namespace, -ns: root namespace recorded as a hint for code generation.
• --include-views: include database views in the schema.
• --include-procs: include stored procedures (default true).
• --overwrite: overwrite an existing file without prompting.

generate#

Generate C# entity classes and strongly typed stored-procedure classes from kiwi-schema.json. No database connection is needed.

• --schema-file, -s: path to the schema file (default kiwi-schema.json).
• --output-folder, -o: folder for generated files (default Generated).
• --namespace, -ns: root namespace (overrides the one in the schema file).
• --entities-file: entity file name (default Entities.cs).
• --procs-file: stored-procedure file name (default StoredProcedures.cs).
• --views-file: separate file name for views (default Views.cs; when omitted, views go into Entities.cs).
• --no-procs: skip stored-procedure generation.
• --context-group, -g: the group name written into [DbContextObject("...")] on every generated class (default Default). Register the group with AddDbObjects("<group>") in your context, or pass an empty value to register classes manually.

install-driver#

Install the NuGet database driver for a provider.

• --provider, -db (required): provider to install a driver for.
• --project, -p: path to a .csproj (auto-detected if omitted); used only with --add-to-project.
• --add-to-project: also add the driver package to the project. Without it your project is never modified: the tool restores the driver into its own cache (~/.kiwi-orm/drivers, overridable with KIWI_ORM_DRIVER_CACHE).

list-providers#

List all supported providers with their NuGet packages and connection-string templates. No options.

Model-first: code to database#

model-init#

Create kiwi-orm.json, migrations/schema.json and migrations/schema-changes.sql.

• --project, -p (required): project name (the .csproj file name without the extension).
• --provider, -db (required): target provider.
• --namespace, -ns (required): root namespace of the project, for example MyApp.Data.
• --migrations-folder, -m: folder for migration files (default migrations).

model-add-change#

Diff entity declarations against the schema snapshot and append a new migration block to schema-changes.sql. Run dotnet build first.

• --description, -d (required): short description, for example AddMiddleName.
• --assembly, -asm: path to the compiled project DLL (otherwise bin/Debug, then bin/Release).
• --migrations-folder, -m: migrations folder (default migrations).
• --author, -a: author recorded in the block (default: the OS user).
• --provider, -db: overrides kiwi-orm.json.
• --rename: confirm renames so data is kept instead of dropped. "Orders=Sales" renames a table and "Items.Name=Title" a column (use the table's new name if it is renamed too). Separate several with ;.

model-apply#

Apply pending migration blocks to a database, transactionally.

• --connection, -c (required): connection string.
• --provider, -db: overrides kiwi-orm.json.
• --migrations-folder, -m: migrations folder.
• --dry-run: show the SQL that would run without changing anything.
• --from-snapshot: apply the full schema from the snapshot as a baseline. For new databases only; it skips replaying all blocks. Requires --connection.
• --environment, -env: label shown in the output, for example staging or production.

model-status#

Show which blocks are applied and which are pending. Options: --connection / -c (required), --provider / -db, --migrations-folder / -m.

model-verify#

Compare the live database schema against schema.json and report drift, which is any change made outside of migrations. Options: --connection / -c (required), --provider / -db, --migrations-folder / -m.

model-rebuild#

Rebuild schema.json from schema-changes.sql. This resolves merge conflicts on schema.json and needs no database. Options: --migrations-folder / -m, --provider / -db.

model-rollback#

Apply the rollback section of the last applied migration block.

• --connection, -c (required): connection string.
• --provider, -db, --migrations-folder, -m: as above.
• --target, -t: the migration id to roll back. It must be the most recently applied one (default: the most recent).
• --confirm: required to confirm the rollback should execute.
• --allow-data-loss: roll back even if existing rows no longer fit the previous column definitions (longer than the old size, or NULL where it was NOT NULL). The database may truncate or reject them.

Environment#