vormia-go-cli

README

vormia-go-cli

Command-line tool for the Vormia Go application framework. Scaffold projects, run them locally, apply migrations, and verify your environment — the same developer workflow Laravel's artisan provides, built on Cobra and embedded Go templates.

Version: v1.3.0 — Slice 1 (new, serve, doctor) plus starterkit, self-update, and CLI-direct migrate* commands. See RELEASE_NOTES.md. Generators (make:model, …) and db:wipe / db:seed ship alongside their matching framework slices.

Install

go install github.com/vormialabs/vormia-go-cli/cmd/vormia@v1.3.0

Or build from source:

git clone https://github.com/vormialabs/vormia-go-cli.git
cd vormia-go-cli
go build -o vormia ./cmd/vormia

Requires Go 1.26+.

Verify:

vormia --version
# vormia version 1.3.0

Quick start

vormia new blog --db sqlite
cd blog
go mod tidy
vormia serve

Open http://localhost:8080/health — you should see ok.

That path exercises the full stack: CLI scaffolds a project → generated app imports vormia-go and drivers → kernel wires chi + sqlite → serves a request.

Commands

Command	Description
vormia new <name>	Scaffold a new Vormia Go application
vormia serve	Run the application (go run .) from the project root
vormia doctor	Check Go toolchain and project metadata
vormia migrate	Run all pending migrations
vormia migrate:rollback	Roll back the last batch (or --steps=N)
vormia migrate:reset	Roll back all migrations
vormia migrate:refresh	Reset, then re-run all migrations
vormia migrate:status	Show applied vs pending migrations
vormia migrate:version	Show the latest applied migration version
vormia starterkit install	Download the starter kit into the current project
vormia starterkit publish	Generate main.go, .env.example, and INTEGRATION.md from the installed starter kit
vormia self-update	Reinstall the CLI binary via go install (--check to compare only)

vormia new

Creates a working slice-1 application: chi router, chosen database driver, optional Redis cache, a /health route, and .vormia.json metadata for future upgrade tooling.

vormia new blog
vormia new blog --db postgres --cache redis
vormia new blog --module example.com/blog --db mysql

Flag	Default	Choices	Purpose
--module	project name	any Go module path	go.mod module line
--db	sqlite	sqlite, postgres, mysql	database driver
--cache	none	redis, none	cache driver

Generated projects pin v1.0.0 of vormia-go and the selected drivers in go.mod.

vormia serve

Runs go run . in the current directory. Requires .vormia.json at the project root — run it from inside a scaffolded app, not the CLI repo itself.

The app's kernel already handles serving and graceful shutdown; the CLI does not reimplement the run loop.

vormia doctor

Checks that go is on PATH. When run inside a project, also confirms .vormia.json is present.

vormia doctor

vormia migrate*

Runs the vormia-go migrate engine from the CLI (CLI-direct): loads .env, opens a bundled driver (sqlite / postgres / mysql), and applies SQL files under database/migrations/ (<version>.up.sql / <version>.down.sql). The app binary is not involved.

# project root with .vormia.json, .env, and database/migrations/
vormia migrate
vormia migrate --database=mysql2
vormia migrate:rollback --steps=1
vormia migrate:status
vormia migrate:version

Flag	Commands	Purpose
--database	all migrate*	Named connection (DB_<NAME>_*); empty = DB_CONNECTION / "default"
--steps	migrate:rollback	How many to roll back (0 = last batch)

Default connection uses bare DB_* keys (DB_DRIVER, DB_PATH, …). A named connection such as mysql2 uses DB_MYSQL2_DRIVER, DB_MYSQL2_HOST, and so on.

Not yet shipped: migrate:fresh, db:wipe, db:seed, db:fresh.

vormia self-update

Reinstalls the CLI binary via go install into GOPATH/bin (or GOBIN):

vormia self-update                  # @latest
vormia self-update --version v1.3.0 # pin an exact version
vormia self-update --check          # compare current vs latest; do not install

Requires go on PATH. When --check is set, --version is ignored (always compares against the latest stable GitHub release). Only replaces a binary that was installed with go install; a hand-built ./vormia elsewhere is not updated.

Starter kit

vormia new gives you a minimal chi + driver + /health app. For a fuller folder structure — config/, database/, internal/handlers, internal/services, internal/routes, internal/middleware, pkg/utils — install the vormia-go-starter-kit into an existing project (one you scaffolded with vormia new, or wrote by hand):

cd blog                                    # a project with .vormia.json + go.mod
vormia starterkit install                  # latest stable release
vormia starterkit install --version v1.0.1 # pin an exact version
vormia starterkit install --beta --version v1.1.0-beta.1  # pin a pre-release

vormia starterkit publish                  # prompts for drivers, then output mode
vormia starterkit publish --drivers sqlite,postgres

install downloads the release tarball from public github.com release URLs (not the REST API) and extracts config/, database/, internal/, logs/, and pkg/ into your project, rewriting their import paths to your module. It is additive — it never overwrites a file that already exists; anything already present is reported as skipped, so it is safe to re-run after a version bump.

publish then renders main.go (print to stdout, write main.go.example, or overwrite main.go with a main.go.bak backup), .env.example, and an INTEGRATION.md checklist for the database/cache drivers you select. The only integration point in your own main.go is one line after app.New(...):

routes.Register(k, nil) // nil = default stdout logger

See the starter kit's own README for what each generated folder is for and aiguide/GUIDE.md for the full install/publish command contract.

Generated project

vormia new blog --db sqlite produces:

blog/
├── main.go           # kernel + chi + driver wiring + /health route
├── go.mod            # pinned framework and driver versions
├── .env.example      # APP_PORT, DB_*, REDIS_* placeholders
├── .gitignore
└── .vormia.json      # project metadata (name, module, drivers, framework version)

Templates ship inside the CLI binary via //go:embed — vormia new works anywhere with no external template files.

Local development

Scaffolded apps resolve dependencies from GitHub. For local end-to-end testing before tags are published, add replace directives to the generated go.mod:

replace github.com/vormialabs/vormia-go => ../vormia-go
replace github.com/vormialabs/vormia-go-driver-chi => ../vormia-go-driver-chi
replace github.com/vormialabs/vormia-go-driver-sqlite => ../vormia-go-driver-sqlite

Then go mod tidy and vormia serve work against your local checkouts. The CLI itself may also use a replace for vormia-go while developing against an unpushed framework tag.

Updating the CLI and related packages

The vormia binary and the packages it scaffolds into your projects are separate Go modules — updating one never touches the other.

What	Check for updates	Update
vormia CLI binary	vormia self-update --check (or compare vormia --version to releases)	vormia self-update or vormia self-update --version vX.Y.Z (alternate: go install github.com/vormialabs/vormia-go-cli/cmd/vormia@latest)
Framework / drivers inside a generated app	From the project root: go list -m -u all (flags modules with newer versions)	go get github.com/vormialabs/vormia-go@latest (repeat per driver/core you use), then go mod tidy
Starter kit folders inside a project	Re-running install is always safe — it never overwrites existing files	vormia starterkit install or vormia starterkit install --version vX.Y.Z

Rebuilding from a source checkout instead of self-update / go install:

cd vormia-go-cli
git pull
go build -o vormia ./cmd/vormia

Testing

go test -v ./...
go vet ./...

Scaffold tests render into a temp directory and verify file output without building the generated project (that requires published or replaced modules). Migrate tests use a temp SQLite project under internal/commands.

Roadmap

Commands are added alongside the framework slices they depend on — no stubs with broken output.

Command	Waits on
make:model, make:controller, make:service	Framework ORM slice
migrate:fresh, db:wipe, db:fresh	db.Wipe in vormia-go
db:seed	Seeder model (SQL under CLI-direct, or Go seeders via app-console)
upgrade (bump a project's pinned framework/driver versions)	Release manifests

Related packages

Package	Role
vormia-go	Application kernel, contracts, db registry, migrate engine
vormia-go-driver-chi	Chi router driver
vormia-go-driver-sqlite	SQLite database driver
vormia-go-driver-postgresql	PostgreSQL database driver
vormia-go-driver-mysql	MySQL database driver
vormia-go-driver-redis	Redis cache driver
vormia-go-starter-kit	Fuller folder scaffold installed via vormia starterkit install

License

MIT — see LICENSE.