CLI Reference

The ninjadog CLI is distributed as a .NET global tool for project scaffolding and code generation.

Installation

dotnet tool install -g Ninjadog

After installation, run ninjadog --help to verify the tool is available.

Typical Workflow

ninjadog init              Create a new project (interactive)
       |
  edit config              Define your entities in ninjadog.json
       |                       --- or ---
ninjadog add-entity        (Optional) Add more      ninjadog ui
       |                   entities from the CLI    Launch the visual
ninjadog validate          Check your config         config builder
       |                   for errors                    |
ninjadog build             Run the generators        ninjadog build
       |
  dotnet run               Launch your API

ninjadog update            Refresh schema after upgrading the CLI

Commands

ninjadog init

Initializes a new Ninjadog project in the current directory. By default, init runs in interactive mode, prompting you for project details, then writes the configuration with a sample Person entity to get you started.

ninjadog init

Options:

Template and use case selection

When you run ninjadog init interactively, the CLI first asks you to choose a template and a use case:

Selecting TodoApp or RestaurantBooking creates a fully configured ninjadog.json with pre-defined entities, relationships, and seed data. Selecting Custom continues with the interactive prompts below.

Interactive prompts (Custom use case)

When you select the Custom use case, the CLI asks for the following project settings:

Press Enter at any prompt to accept the default value.

Example session

$ ninjadog init
? Project name: MyApi
? Version: 1.0.0
? Description: My REST API
? Root namespace: MyApi
? Output path: src/applications/MyApi
Ninjadog settings file created successfully.

This creates a ninjadog.json in the current directory:

{
  "config": {
    "name": "MyApi",
    "version": "1.0.0",
    "description": "My REST API",
    "rootNamespace": "MyApi",
    "outputPath": "src/applications/MyApi",
    "saveGeneratedFiles": true
  },
  "entities": {
    "Person": {
      "properties": {
        "Id": { "type": "Guid", "isKey": true },
        "FirstName": { "type": "string" },
        "LastName": { "type": "string" },
        "BirthDate": { "type": "DateTime" }
      }
    }
  }
}

Examples:

# Interactive mode (prompts for template and use case)
ninjadog init

# Scaffold TodoApp use case directly
ninjadog init --use-case TodoApp

# Scaffold RestaurantBooking use case
ninjadog init -u RestaurantBooking

# Non-interactive with defaults
ninjadog init --default

# Non-interactive with custom values
ninjadog init --name MyApi --namespace MyApi.Web

# Generate from natural language (requires ANTHROPIC_API_KEY)
ninjadog init --from-prompt "A blog platform with users, posts, tags, and comments"

The generated Person entity is a starter template. Replace or extend it with your own domain entities before running ninjadog build.

A ninjadog.json file must not already exist in the current directory. If one is found, the command exits with an error to avoid overwriting your configuration.

ninjadog validate

Validates your ninjadog.json configuration file against the schema and checks for common errors.

ninjadog validate [OPTIONS]

Options:

Exit codes:

Example output:

$ ninjadog validate

Validating ninjadog.json...

  ERROR  NINJ001  Entity "Product" has no properties defined.
  ERROR  NINJ003  Property "Product.Id" is marked as key but type "string" has no maxLength.
  WARN   NINJ007  Entity "Order" has no key property. A Guid key named "Id" will be added.

Result: 2 errors, 1 warning

Validation rules:

Run ninjadog validate before ninjadog build to catch configuration mistakes early. In CI pipelines, use --strict to ensure warnings are not ignored.

ninjadog add-entity

Adds a new entity to your existing ninjadog.json configuration file. The entity is created with a default Guid primary key.

ninjadog add-entity <EntityName>

The entity name should be in PascalCase (e.g., Product, OrderItem). A ninjadog.json file must already exist in the current directory – run ninjadog init first if you haven’t already.

Example:

ninjadog add-entity Product

This appends a Product entity to the entities section of your ninjadog.json:

{
  "entities": {
    "Person": { ... },
    "Product": {
      "properties": {
        "Id": {
          "type": "Guid",
          "isKey": true
        }
      }
    }
  }
}

After adding an entity, open ninjadog.json to define additional properties before running ninjadog build.

ninjadog update

Updates the ninjadog.schema.json file in the current directory to the version embedded in the installed CLI tool. This is useful after upgrading Ninjadog to get IDE autocompletion and validation for newly added configuration options.

ninjadog update

Example:

$ ninjadog update
Schema file updated successfully.
  -> ninjadog.schema.json

Run ninjadog update after upgrading the CLI tool to ensure your local schema stays in sync with the installed version.

ninjadog build

Builds and runs the generator engine against your project configuration. This reads the ninjadog.json file in the current directory and produces the generated source files.

ninjadog build

ninjadog ui

Launches a local web server that hosts a visual configuration builder for your ninjadog.json file. The UI lets you create and edit entities, enums, and seed data through a browser-based interface instead of editing JSON by hand.

ninjadog ui [OPTIONS]

Options:

Visual builder features:

• Entity editor – Add, rename, clone, and remove entities. Define properties with types, key markers, and validation rules. Drag-and-drop property reordering, quick-add presets (ID, Name, Timestamps, Email, Description), and bulk property actions.
• Enum editor – Define enums with named values. Inline add/remove with two-click delete confirmation.
• Seed data editor – Populate initial data rows for each entity. Auto-generated key values (Guid, int, long), CSV/JSON import, and cell-level type validation.
• Live JSON preview – See the generated ninjadog.json update in real time with Monaco Editor syntax highlighting and schema validation.
• Validation – Live schema validation with error paths displayed inline.
• Undo / Redo – Full undo/redo history (up to 50 states) with Ctrl+Z / Ctrl+Y keyboard shortcuts.
• AI Assistant – Describe your API in plain English and generate a complete configuration. Toggle the chat panel with the sparkle icon or Ctrl+Shift+A. Supports multi-turn conversation for iterating on the schema. Requires ANTHROPIC_API_KEY environment variable.
• Keyboard shortcuts – Ctrl+S save, Ctrl+B build, Ctrl+E add entity, Ctrl+Shift+A AI assistant, 1–4 switch tabs, ? show shortcut overlay.
• Auto-save – Optional auto-save to localStorage with 3-second debounce.
• View modes – Toggle between Split View (form + JSON), Form Only, or JSON Only layouts.
• Template picker – Start from pre-built templates (Blank, Todo App, Blog API, E-Commerce) instead of an empty configuration.
• Import – Import seed data from CSV or JSON arrays via a modal dialog.
• Export – Download the current configuration as a JSON file.
• Entity color coding – Each entity gets a unique color dot for quick visual identification across all tabs.

By default, ninjadog ui opens your browser automatically. Use --no-open if you are running on a headless server or want to open the URL manually.

A ninjadog.json file must already exist in the target directory. Run ninjadog init first if you haven’t already.

Example:

# Start on the default port and open the browser
ninjadog ui

# Start on a custom port without opening a browser
ninjadog ui --port 8080 --no-open

Next Steps

• Getting Started – Step-by-step tutorial using the CLI tool
• Configuration Reference – Full reference for ninjadog.json
• Architecture – Understand the project structure
• Generators – See what gets generated
• Generated Examples – Real generated code from snapshot tests