CLI reference

Install and create a project

Follow installation for the pinned CLI. Run gonex new shop --module example.com/acme/shop, then cd shop and go mod tidy. Continue with go tool gonex inside the generated application. The command forms below use the executable name; prefix it with go tool in your project.

Project creation

gonex new NAME --module IMPORT_PATH [--framework-version VERSION] [--arch monolith|microservices] [--dry-run]

The architecture defaults to monolith. The framework version defaults to the installed CLI’s resolved module version, including Go pseudo-versions. A CLI built locally must receive an explicit valid --framework-version. The destination must not exist.

Install with go install github.com/amkargar/gonex/cmd/gonex@3ca54b46cb42 for this snapshot, or pin a reviewed commit/published tag. Generated apps include a tool directive: inside the app use go tool gonex for the commands below. Microservices workspaces also have a root tool module; run go mod tidy there after creation.

Modules and services

gonex create module NAME [--transport http|none|grpc|http,grpc] [--http-version vN] [--db] [--service NAME] [--dry-run]
gonex create service NAME [--dry-run]
gonex create client PROVIDER --service CONSUMER --module MODULE [--version v1] [--dry-run]

create service requires a microservices workspace. A client skeleton uses real generated service constructors but leaves domain mapping and injection to the developer. Run go mod tidy in each affected module after adding dependencies.

Adapter changes

gonex module version NAME --http vN [--policy preserve|replace] [--prefix PATH] [--service NAME] [--dry-run]
gonex module enable NAME --grpc [--service NAME] [--dry-run]

Versioning defaults to preserve and /api/vN. replace stops registering legacy routes while retaining their source. Existing version packages are not overwritten. Enabling gRPC preserves handwritten source and requires the supported injectable service factory. See HTTP versions and microservices.

Run and verify

gonex run [--service NAME]
gonex build [--os OS] [--arch ARCH] [--out FILE] [--service NAME]
gonex check [--service NAME]
gonex --help
gonex --version

run invokes the Go executable path for the project; the application displays its bound address and writes structured lifecycle/request logs. See logging. build writes an application executable; check runs tests, vet and package compilation. Child command failures preserve their exit codes. A workspace command must identify a service when selection is ambiguous.

OpenAPI

gonex openapi generate [--out openapi.json] [--http-version vN] [--service NAME] [--dry-run]
gonex openapi validate [--file openapi.json] [--against BASELINE] [--service NAME]

Generation executes the project's initialization/export path without starting listeners, validates the result and writes the output. It exports the legacy document unless --http-version selects a registered major. Validation is offline; --against additionally runs conservative compatibility checks against a baseline. A generation dry run does not execute project code.

Database migrations

gonex db migrate [--service NAME] [--dry-run]
gonex db status [--service NAME] [--dry-run]

Configure DATABASE_URL and, where needed, DATABASE_DIALECT in the executable's environment. Migrations are explicit; serving does not automatically change schemas. Dry runs do not connect to the database. See database behavior.

Protobuf contracts

gonex grpc generate [--dry-run]
gonex grpc check

Run from a supported project/workspace, service or contracts root. Generation compiles and checks contracts, then invokes pinned official plugins and stages the resulting files. Dry runs omit plugins and writes. check compares descriptors to the stored baseline. Neither command substitutes for the release workflow's Buf gate; see gRPC contracts.

Generator safety

Generators plan and validate paths and collisions before writes. They reject traversal, symlinks and handwritten-file overwrites, hash-check tool-owned registries and support dry runs. .gonex.json records ownership metadata; do not delete it to bypass a conflict.

New projects use a staged rename. Existing projects use an exclusive lock, staging and rollback on ordinary application errors; multi-file updates are not power-loss atomic. After an interrupted process, inspect .gonex.lock and proposed changes before recovering. See getting started.

Upgrade your application dependency

Select a reviewed target with go get -tool github.com/amkargar/gonex/cmd/gonex@TARGET. Resolve its canonical module version with go list -m github.com/amkargar/gonex, then run go tool gonex upgrade --framework-version CANONICAL_VERSION --dry-run. Review and apply without --dry-run, followed by go mod tidy, tests and contract comparisons.

Upgrade updates the dependency/tool and .gonex.json version metadata. It preserves handwritten code and registries; it does not migrate application code or database schemas. Review the readiness and release gates before promoting a candidate.

Local microservices workflow

Follow First microservice call for explicit client profiles and wiring, dev/doctor and independently published contracts. Existing generated paths and TLS defaults are retained. Compatibility explains skeleton/example/raw profiles, version coexistence and generation checks.

Help for every command

gonex -h
gonex build --help
gonex create module -h
gonex help create client

Help is grouped by task. Command-specific help lists only relevant options and works outside an application without generating files. Color is automatic on supported terminals and disabled for redirected output, TERM=dumb and NO_COLOR.

Build for an operating system and architecture

go tool gonex build --os windows --arch amd64
go tool gonex build --os windows --arch arm64
go tool gonex build --os linux --arch amd64
go tool gonex build --os linux --arch arm64
go tool gonex build --os linux --arch amd64 --out ./release/server

Gonex uses go build -o <file> . underneath. Target options map to GOOS and GOARCH, defaulting to environment values or the current machine. Supported pairs are checked against go tool dist list. The default executable is dist/<os>-<arch>/<app>, with .exe on Windows. Custom relative output paths resolve from the selected application/service root.

Successful output shows the target and file path; a run command appears only for native targets. Cross-compilation can require a target C toolchain when a dependency uses CGO. Compiler diagnostics and failure exit codes remain visible.