---
title: "CLI Overview"
description: "RoomSharp CLI for scaffolding code, managing migrations, and exporting schemas."
canonical: "https://roomsharp.dev/docs/v0.5.4/cli-overview"
source: "src/content/v0.5.4/cli-overview.mdx"
---

# RoomSharp CLI

A production-grade command-line tool for RoomSharp ORM to scaffold code, manage migrations, and export schemas with safety and validation.

## Overview

RoomSharp CLI is a .NET global tool that provides:

- **Scaffolding**: Entities, DAOs, Database, Manual & Auto Migrations
- **Runtime migrations**: Apply and track schema versions
- **Schema export**: Dump schema for documentation and CI
- **Strict validation**: C#/SQL identifiers, version windows, file safety
- **Multi-provider support**: SQLite (built-in), PostgreSQL, MySQL, SQL Server

## Installation

```bash
dotnet tool install -g RoomSharp.Cli
```

Verify installation:

```bash
room --version
room --docs   # opens CLI docs page
room --help
```

## Quick Start

<Tip title="Prerequisites">
Run these commands inside an existing C# project that references RoomSharp.
</Tip>

```bash
# Install CLI tool
dotnet tool install -g RoomSharp.Cli

# Generate config file for this project
room make:config --provider sqlite --connection "Data Source=app.db" --ns MyApp.Data

# Create new entity (entities are C# classes representing database tables)
room make:entity User --table=users

# Create new DAO (data access objects)
room make:dao User --entity=User

# Create new database class (abstract base class for RoomDatabase)
room make:database AppDatabase --version=1 --entities=User

# Apply migrations and create the database (auto-builds the project)
room migrate:up -b
```

## Command Reference

### Scaffolding Commands

| Command | Description | Key Options |
|---------|-------------|-------------|
| `make:entity <Name>` | Create entity class | `--table`, `--path`, `--ns` |
| `make:dao <Name>` | Create DAO interface | `--entity`, `--table`, `--path`, `--ns` |
| `make:database <Name>` | Create database class | `--version`, `--entities`, `--path`, `--ns` |
| `make:migration <Name>` | Create manual migration | `--from`, `--to`, `--path`, `--ns` |
| `make:auto-migration <Name>` | Create auto migration spec | `--path`, `--ns` |
| `make:seeder <Name>` | Create seeder class | `--entity`, `--order`, `--path`, `--ns` |
| `make:repository <Entity>` | Create repository class | `--path`, `--ns` |
| `make:view <Name>` | Create DatabaseView entity | `--view`, `--query`, `--path`, `--ns` |
| `make:converter <Name>` | Create TypeConverter class | `--from`, `--to`, `--path`, `--ns` |
| `make:config` | Generate `room.config.json` | `--provider`, `--connection`, `--ns` |

> All scaffolding commands support `--force` and `--dry-run` flags.

---

### Migration Commands

<Note>
Use `-b` to auto-build the project before running these commands.
</Note>

| Command | Description | Key Options |
|---------|-------------|-------------|
| `migrate:up` | Apply pending migrations | `--to`, `--fallback-destructive` |
| `migrate:status` | Show current migration status | |
| `migrate:timeline` | Visual migration history with status | |
| `migrate:plan` | Preview migration chain | `--to` |
| `migrate:verify` | Verify applied checksums | |
| `migrate:rollback` | Roll back migrations | `--to`, `--steps`, `--force` |
| `migrate:set-version` | ⚠️ Force set version (DANGEROUS) | `--to`, `--force` |

---

### Database Commands

| Command | Description | Key Options |
|---------|-------------|-------------|
| `database:drop` | Drop database | `--force` |
| `database:reset` | Drop + migrate:up | `--force`, `--fallback-destructive` |
| `database:seed` | Run seeders | `--env`, `--only`, `--skip`, `--plan`, `--dry-run` |

---

### Inspection Commands

| Command | Description |
|---------|-------------|
| `info` | Show project and database info |
| `doctor` | Run health checks on project configuration |
| `db:tables` | List all tables with row counts |
| `db:describe <Table>` | Show table structure (columns, types, keys) |
| `db:stats` | Show database statistics (size, rows, indexes) |

---

### Schema Commands

| Command | Description | Key Options |
|---------|-------------|-------------|
| `schema:export` | Export schema as JSON or SQL | `--out`, `--sql` |
| `schema:validate` | Validate schema against live DB | `--schema` |
| `generate:diagram` | Generate ERD (Mermaid/DBML) | `--output`, `--format` |

---

### Query Command

| Command | Description | Key Options |
|---------|-------------|-------------|
| `query <SQL>` | Execute SQL query | `--format`, `--max-rows`, `--file`, `--allow-writes` |

## Project Requirements

The CLI **must** be run inside a C# project that references **RoomSharp**. It will refuse execution otherwise.

Runtime commands (`migrate:*`, `schema:export`) require:
- A valid `RoomDatabase` implementation
- A built project (`dotnet build`)
- Provider + connection string via config or flags

## Configuration (room.config.json)

Optional but recommended. Place at the project root.

<Tip>
Once configured, you no longer need to pass `--provider` and `--connection` flags with every command — the CLI reads them automatically from your config file.
</Tip>

```json
{
  "provider": "sqlite|pgsql|mysql|sqlserver",
  "connectionString": "Data Source=room.db",
  "buildConfiguration": "Debug",
  "paths": {
    "entities": "Data/Models",
    "daos": "Data/Daos",
    "database": "Data/Database",
    "migrations": "Data/Migrations",
    "autoMigrations": "Data/Migrations/Auto",
    "schema": "Data/Schemas",
    "seeders": "Data/Database/Seeders",
    "views": "Data/Views",
    "converters": "Data/Converters",
    "repositories": "Data/Database/Repositories"
  },
  "namespaceRoot": "MyApp.Data"
}
```

Generate it fast:

```bash
room make:config --provider sqlite --connection "Data Source=room.db" --ns MyApp.Data
```

## Connection String References

Instead of hardcoding connection strings, you can reference external sources:

### From appsettings.json

```json
{
  "connectionString": "$appsettings:ConnectionStrings:DefaultConnection"
}
```

### From Environment Variables

```json
{
  "connectionString": "$env:DATABASE_URL"
}
```

```bash
# PowerShell
$env:DATABASE_URL = "Data Source=app.db"
room migrate:status -b

# Bash
room migrate:status -b
```

## Global Flags

| Flag | Description |
|------|-------------|
| `--provider` | Override provider |
| `--connection` | Override connection string |
| `--config` | Path to room.config.json |
| `-b`, `--build` | Auto-build project before running command |
| `-r`, `--release` | Build in Release mode (use with `-b`) |
| `--force` | Overwrite files |
| `--dry-run` | Preview without writing |
| `--fallback-destructive` | Allow destructive fallback |

## Auto-Build Flag

The `-b` / `--build` flag automatically builds your project before running commands that require a compiled assembly:

```bash
# Instead of:
dotnet build
room migrate:status

# Just use:
room migrate:status -b
```

Output:
```
⠋ Building project (Debug)... (2.1s)
✓ Build succeeded (3.2s)

Current version : 1
Target version  : 3
Pending migrations:
  • Migration_1_2 (1 → 2)
  • Migration_2_3 (2 → 3)
```

## Next Steps

- [Scaffolding Commands](/docs/v0.5.4/cli-scaffolding) - Generate entities, DAOs, and databases
- [Migration Commands](/docs/v0.5.4/cli-migrations) - Apply and manage schema migrations
- [Inspection Commands](/docs/v0.5.4/cli-inspection) - Inspect database state and project info