CLI Usage

CLI (design-time KSQL, Avro & AI assist)

Ksql.Linq.Cli is a .NET tool that can generate KSQL DDL scripts and Avro schemas from your design-time context (KsqlContext / IDesignTimeKsqlContextFactory).

Example: install as a global tool
dotnet tool install -g Ksql.Linq.Cli

---

Generate KSQL scripts with dotnet ksql script

Generate KSQL DDL scripts (including CREATE STREAM/TABLE and CSAS/CTAS) from a design-time KsqlContext.

dotnet ksql script ^
  --project ./src/MyApp/MyApp.csproj ^
  --output  ./ksql/generated.sql ^
  --verbose

• Loads the target assembly and obtains a KsqlContext via IDesignTimeKsqlContextFactory.
• Uses DefaultKsqlScriptBuilder to generate DDL.
• WITH (...) clauses include KAFKA_TOPIC, VALUE_FORMAT, PARTITIONS, REPLICAS, RETENTION_MS, VALUE_SCHEMA_SUBJECT, and more.

---

Generate Avro schemas with dotnet ksql avro

Generate value Avro schemas for entities registered in the design-time KsqlContext and write them as .avsc files.

dotnet ksql avro ^
  --project ./src/MyApp/MyApp.csproj ^
  --output  ./schemas/ ^
  --verbose

• Internally calls DefaultAvroSchemaExporter.ExportValueSchemas(context) to obtain a Dictionary<string, string>
  (key: entity type name, value: Avro schema JSON).
• Writes files under the directory specified by --output using <TypeName>.avsc naming,
  e.g. Examples_DesigntimeKsqlScript_OrderEvent.avsc.

---

Main options

The following options apply to Ksql.Linq.Cli 1.0.0 and later (earlier 0.9.x versions are mostly compatible unless otherwise noted).

• -p, --project (required)
  Path to the target project or DLL.
  This assembly must contain a design-time KsqlContext and an IDesignTimeKsqlContextFactory.

• -c, --context
  Name of the KsqlContext class to use when multiple design-time contexts/factories are available in the same assembly.

• -o, --output

  • For script: file path to write the generated KSQL script.
  • For avro (required): directory where generated .avsc files are written; created if it does not already exist.
  • If omitted (where allowed), results are written to standard output.

• --config
  Path to an appsettings.json file to use for configuration instead of the default location.

• -v, --verbose
  Outputs detailed logs about CLI processing (target assembly, selected context, entities, output paths, etc.).

---

AI-assisted workflows with dotnet ksql ai-assist

Ksql.Linq.Cli also provides an ai-assist command that helps you use modern AI coding assistants (ChatGPT, Claude, Gemini, Copilot, etc.) together with Ksql.Linq.

Basic flow:

1. Ensure the CLI is installed (v1.0.0 or later):

   dotnet tool install --global Ksql.Linq.Cli --version 1.0.0

2. Copy the AI Assistant Guide (AI_ASSISTANT_GUIDE.md) to your clipboard:

   dotnet ksql ai-assist --copy

3. Paste it into your AI console and ask the assistant to act as a design partner for your Ksql.Linq project (schema design, windowing strategy, CLI usage, etc.).

The guide contains prompt patterns, recommended workflows, and anti-patterns tailored to Ksql.Linq, so AI suggestions stay aligned with the library’s model and conventions.

---

Typical usage pattern

• Prepare a dedicated design-time KsqlContext (for example, with IsDesignTime = true and SkipSchemaRegistration = true) separate from the runtime context.
• Implement IDesignTimeKsqlContextFactory similarly to the examples/designtime-ksql-* samples.
• Run dotnet ksql script and dotnet ksql avro in CI/CD or local development to continuously generate and manage DDL and Avro schemas.

---

Sample projects

You can see end-to-end usage of a design-time KsqlContext and factory in the following examples from the main repository:

• examples/designtime-ksql-script
  Minimal design-time context (OrdersKsqlContext + OrdersDesignTimeKsqlContextFactory) that produces KSQL DDL for a simple event and summary view.
  Example: generate a KSQL script from this sample:

  cd path/to/Ksql.Linq
  dotnet ksql script ^
    --project ./examples/designtime-ksql-script/DesigntimeKsqlScript.csproj ^
    --output  ./ksql/designtime-orders.sql ^
    --verbose

• examples/designtime-ksql-tumbling
  Design-time context (TumblingKsqlContext + TumblingDesignTimeKsqlContextFactory) that focuses on Tumbling-window aggregations (using Tumbling(...), GroupBy, WindowStart(), etc.).
  Example: generate a KSQL script (including the Tumbling view) from this sample:

  cd path/to/Ksql.Linq
  dotnet ksql script ^
    --project ./examples/designtime-ksql-tumbling/DesigntimeKsqlTumbling.csproj ^
    --output  ./ksql/designtime-tumbling.sql ^
    --verbose