Your First App

Create a new project with the Spine CLI and check that GET /health returns {"status":"ok"}. Read the generated files to see how the app is configured, validated, and run.

Go 1.25.5 or later is required, and the CLI recommends Go 1.27.3. The time needed to download dependencies for the first time depends on your environment.

1. Install the CLI and Check the Command

go install github.com/NARUBROWN/spine-cli/cmd/spine@v0.1.4
spine version

spine version prints spine-cli 0.1.4. If the command cannot be found, check the Go executable path setup in the installation guide.

2. Create a Project

Run these commands in the parent directory where you want to place the project. If a hello-spine directory already exists, use a different name.

spine new hello-spine --module example.com/hello-spine
cd hello-spine
go mod tidy

The project files are created in the hello-spine directory. The CLI specifies Spine v0.5.1 in go.mod, and go mod tidy downloads the required dependencies.

3. Inspect the Generated Structure

hello-spine/
├── .gitignore
├── README.md
├── go.mod
├── main.go
├── spine.toml
└── internal/application/
    ├── application.go
    └── application_test.go

The project contains main.go, which starts execution, and the internal/application directory, which holds the app configuration code. spine.toml tells the CLI the module path, execution entry point, location of the app configuration code, and port.

module = "example.com/hello-spine"
entrypoint = "."
composition = "./internal/application"
port = 8080

BuildApplication() in internal/application/application.go returns the app and its runtime options. The generated code registers the HealthController constructor and GET /health, and explicitly sets the HTTP runtime options, boot.HTTPOptions.

When adding a feature, put route, constructor, and interceptor registrations in this function or in a Register(app) error function it calls. Project Structure covers this in detail.

main.go is already generated, so you do not need to modify it. The following code shows the order of app configuration, validation, and execution.

func main() {
    app, options, err := application.BuildApplication()
    if err != nil {
        log.Fatal(err)
    }
    if err := app.Validate(options); err != nil {
        log.Fatal(err)
    }
    if err := app.Run(options); err != nil {
        log.Fatal(err)
    }
}

4. Validate the App Configuration and Code

Run these commands in the root directory of the generated project.

spine doctor
spine inspect
spine contract check
spine verify

doctor diagnoses tools and project settings. inspect shows the app configuration registered in code, including routes and dependencies. The CLI calls this information extracted from registration code the execution contract.

contract check checks the execution contract. verify also runs gofmt, go vet, and Go tests in addition to the contract check. The generated application_test.go also checks BuildApplication() and app.Validate(options) without starting the server. Once all commands complete without errors, you are ready to run the server.

5. Run the App and Check the Response

spine dev

With the server running, open another terminal and send a request.

curl http://localhost:8080/health

{"status":"ok"}

If the server returns the JSON response above, GET /health is working. Press Ctrl+C in the terminal running the server to stop the development server.

Next Steps

• Follow Project Structure to add a feature to the generated project.
• Read Controllers to learn about routes and handlers.
• Follow Database to connect Bun ORM to a repository.