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.4.1 — Slice 1 plus starterkit, self-update, CLI-direct migrate* / db:*, toolchain wrappers, make:* generators, and upgrade. See RELEASE_NOTES.md. Commands that still need new framework APIs (cache:*, route:list, …) wait on vormia-go.

Install

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

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.4.1

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 run dev	Alias of serve
vormia build / vormia run build	Build to bin/<name> (go build)
vormia test	Run tests (go test ./...)
vormia tidy	Tidy modules (go mod tidy)
vormia install / vormia install <pkg>	go mod download or go get <pkg>
vormia about	Print .vormia.json
vormia upgrade	Bump Vormia modules in go.mod to @latest, then tidy
vormia make:handler / make:service / make:model / …	Generate stubs under internal/
vormia make:migration <name>	Create .up.sql / .down.sql migration pair
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:fresh	Drop all tables, then re-run all migrations
vormia migrate:status	Show applied vs pending migrations
vormia migrate:version	Show the latest applied migration version
vormia db:wipe	Drop all tables on the target connection
vormia db:seed	Run *.sql files in database/seeders
vormia db:fresh	Wipe, migrate, then seed
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* / db:*

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). Wipe and seed use db.Wipe and seed.Run against database/seeders/*.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:fresh
vormia migrate:status
vormia migrate:version
vormia db:wipe
vormia db:seed
vormia db:fresh

Flag	Commands	Purpose
--database	all migrate* / db:*	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.

migrate:fresh drops all tables then runs Up (does not replay .down.sql). migrate:refresh still resets via downs then ups. db:fresh is wipe → migrate → seed.

Toolchain wrappers

Run from a project root (requires .vormia.json):

vormia about                 # pretty-print .vormia.json
vormia tidy                  # go mod tidy
vormia install               # go mod download
vormia install github.com/x/y
vormia test                  # go test ./...
vormia build                 # go build -o bin/<name> .
vormia run build             # alias of build
vormia run dev               # alias of serve
vormia upgrade               # go get @latest for Vormia modules in go.mod, then tidy

Generators (make:*)

File stubs only — no framework runtime. Refuses to overwrite existing files.

vormia make:handler UserHandler
vormia make:service UserService
vormia make:model User
vormia make:middleware Auth
vormia make:adapter Stripe
vormia make:provider CacheProvider
vormia make:test user_service
vormia make:migration create_users

make:controller is a deprecated alias of make:handler.

vormia self-update

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

vormia self-update                  # @latest
vormia self-update --version v1.4.1 # 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)	vormia upgrade (or manual go get …@latest + 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

Shipped in v1.4.1: migrate:fresh, db:wipe, db:seed, db:fresh (vormia-go v1.2.1+). Remaining commands wait on framework APIs — no broken stubs.

Command	Waits on
cache:ping / cache:clear / cache:forget	Cache registry helpers in vormia-go
route:list	Router introspection
make:route, make:job, queue:*, schedule:*, …	Matching subsystems

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.