CLI Reference

Every command, every flag. For the people who live in the terminal and wouldn't have it any other way.

Overview

The seedorm CLI handles project initialization, running a dev server, managing migrations, and launching a visual data browser. Four commands that do more than most CLIs with forty.

$ seedorm --help
Usage: seedorm [options] [command]
Development-first ORM. Start with JSON, migrate to any SQL database
Options:
  -V, --version     output the version number
  -h, --help        display help for command
Commands:
  init [options]    Initialize a new seedorm project
  start [options]   Start the development REST API server
  migrate           Migration commands
  studio [options]  Launch the seedorm studio UI
  help [command]    display help for command

`seedorm init`

Initializes a new seedorm project in the current directory. Three files, zero questions asked.

$ seedorm init
✓  Created seedorm.config.json
✓  Created data/ directory
✓  Created migrations/ directory
info  Run `seedorm start` to launch the dev server

Options

Flag	Description
`-f, --force`	Overwrite existing config file

What it creates

seedorm.config.json: configuration file with JSON adapter defaults
data/: directory where JSON data files are stored
migrations/: directory for migration files

Default configuration

seedorm.config.jsonjson

{
  "adapter": {
    "adapter": "json",
    "path": "./data"
  },
  "migrationsDir": "./migrations"
}

`seedorm start`

Starts a development REST API server that exposes your data over HTTP. Useful for prototyping frontends, testing with curl, or just feeling productive before your morning coffee kicks in.

$ seedorm start
✓  Connected to database
seedorm dev server
info  Listening on http://localhost:4100
REST API: GET/POST/PUT/DELETE /api/:collection/:id

Options

Flag	Default	Description
`-p, --port <port>`	`4100`	Port to listen on

REST API endpoints

Method	Endpoint	Description
`POST`	`/api/models`	Register a model dynamically
`GET`	`/api/collections`	List all collections
`GET`	`/api/:collection`	List documents (supports `?filter=`, `?limit=`, `?offset=`, `?sort=`)
`GET`	`/api/:collection/:id`	Get a document by ID
`POST`	`/api/:collection`	Create a document
`PUT/PATCH`	`/api/:collection/:id`	Update a document
`DELETE`	`/api/:collection/:id`	Delete a document

Query parameters

The GET /api/:collection endpoint supports query parameters for filtering, sorting, and pagination:

# Filter by age >= 18
$ curl 'http://localhost:4100/api/users?filter={"age":{"$gte":18}}'
# Sort by name ascending, limit to 10
$ curl 'http://localhost:4100/api/users?sort={"name":1}&limit=10'
# Paginate: page 2 with 20 per page
$ curl 'http://localhost:4100/api/users?limit=20&offset=20'

`seedorm migrate`

Migration management commands. Create, run, and manage schema migrations. Because your side project just got real users and now you need a real database.

`seedorm migrate create <name>`

Creates a new migration file in the migrations directory.

$ seedorm migrate create add-users-table
✓  Created migration: migrations/1709234567890_add-users-table.json
Edit the migration file to add your up/down steps

Flag	Description
`--empty`	Create an empty migration (no auto-generated steps)

Migration file format

migrations/1709234567890_add-users-table.jsonjson

{
  "id": "1709234567890_add-users-table",
  "name": "add-users-table",
  "timestamp": 1709234567890,
  "up": [
    {
      "type": "createCollection",
      "collection": "users"
    },
    {
      "type": "addField",
      "collection": "users",
      "field": "email",
      "schema": {
        "type": "string",
        "required": true,
        "unique": true,
        "index": true
      }
    }
  ],
  "down": [
    {
      "type": "dropField",
      "collection": "users",
      "field": "email"
    },
    {
      "type": "dropCollection",
      "collection": "users"
    }
  ]
}

Migration step types

Type	Description
`createCollection`	Create a new collection/table
`dropCollection`	Drop a collection/table
`addField`	Add a field/column
`dropField`	Remove a field/column
`alterField`	Change a field's type or constraints
`addIndex`	Create an index
`dropIndex`	Remove an index

`seedorm migrate up`

Runs all pending migrations in order.

$ seedorm migrate up
✓  Applied: 1709234567890_add-users-table
✓  Applied: 1709234567891_add-posts-table
info  2 migration(s) applied

Flag	Description
`-c, --count <n>`	Run only the next `n` migrations

`seedorm migrate to <target>`

Exports your current JSON data as SQL. Currently supports postgres. Generates CREATE TABLE statements and INSERTstatements for all documents.

# Print SQL to stdout
$ seedorm migrate to postgres
# Write to a file
$ seedorm migrate to postgres --output export.sql
# Export specific collection
$ seedorm migrate to postgres --collection users --output users.sql

Flag	Description
`-o, --output <file>`	Write SQL to a file instead of stdout
`--collection <name>`	Export only a specific collection

Example output

-- Export of "users" from seedorm
-- Generated at 2025-03-01T12:00:00.000Z
CREATE TABLE IF NOT EXISTS "users" (
  "id" TEXT PRIMARY KEY,
  "createdAt" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  "updatedAt" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  "name" TEXT NOT NULL,
  "email" TEXT UNIQUE,
  "age" DOUBLE PRECISION
);
CREATE INDEX IF NOT EXISTS "idx_users_age" ON "users" ("age");
INSERT INTO "users" ("id", "name", "email", "age", "createdAt", "updatedAt")
  VALUES ('usr_abc123', 'Alice', 'alice@test.com', 30, '2025-...', '2025-...');

`seedorm studio`

Launches a visual web UI for browsing and editing your data. Opens in your default browser. For when you want to see your data without writing a single query.

$ seedorm studio
✓  Connected to database
seedorm studio
info  Open http://localhost:4200 in your browser

Options

Flag	Default	Description
`-p, --port <port>`	`4200`	Port to serve the studio UI on

Features

Browse all collections in a sidebar
View documents in a sortable table
Click any row to edit the full document JSON
Add new documents with a form
Delete documents with confirmation

Configuration file

SeedORM looks for configuration in the current directory. It checks these filenames in order (because we couldn't pick just one):

seedorm.config.json
seedorm.json

If no config file is found, defaults are used (JSON adapter with ./data path).

Full config reference

seedorm.config.jsonjson

{
  "adapter": {
    "adapter": "json" | "postgres" | "mysql",
    "path": "./data",               // JSON only: data directory
    "url": "postgres://..."          // SQL only: connection string
  },
  "migrationsDir": "./migrations"    // path to migration files
}

When configuring adapters in TypeScript, you can use the AdapterType enum for type safety:

import { SeedORM, AdapterType } from "seedorm";
const db = new SeedORM({
  adapter: { adapter: AdapterType.Postgres, url: "postgres://..." },
});