internal/website/docs/getting-started.md
Go Micro provides two ways to get started: the CLI (recommended) or manual setup.
Go Micro has a clear lifecycle for development through deployment:
| Stage | Command | Purpose |
|---|---|---|
| Create | micro new myservice | Scaffold a service (--template crud/pubsub/api) |
| Develop | micro run | Local dev with hot reload and API gateway |
| Test | micro call | Call a service endpoint from the CLI |
| Chat | micro chat | Talk to your services through an LLM |
| Gateway | micro api | Standalone HTTP-to-RPC gateway |
| Build | micro build | Compile production binaries |
| Deploy | micro deploy | Push to a remote Linux server via SSH + systemd |
| Dashboard | micro server | Production web UI with auth |
Install the CLI:
go install go-micro.dev/v5/cmd/[email protected]
Note: Use a specific version instead of
@latestto avoid module path conflicts. See releases for the latest version.
Create and run a service:
micro new helloworld
cd helloworld
micro run
Or scaffold a CRUD service with a ready-made template:
micro new contacts --template crud
cd contacts
micro run
Open http://localhost:8080 to see your service and call it from the browser.
The gateway proxies HTTP to RPC:
curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \
-H "Content-Type: application/json" \
-d '{"name": "World"}'
micro run gives you:
http://localhost:8080http://localhost:8080/agent — AI chat with MCP toolshttp://localhost:8080/api — browse endpoints and schemashttp://localhost:8080/api/{service}/{method}http://localhost:8080/mcp/tools — services exposed as AI toolshttp://localhost:8080/healthSee the micro run guide for configuration, multi-service projects, and more.
If you prefer to set up a service without the CLI:
go get go-micro.dev/v5@latest
This is a basic example of how you'd create a service and register a handler in pure Go.
mkdir helloworld
cd helloworld
go mod init
go get go-micro.dev/v5@latest
Write the following into main.go
package main
import (
"go-micro.dev/v5"
)
type Request struct {
Name string `json:"name"`
}
type Response struct {
Message string `json:"message"`
}
type Say struct{}
func (h *Say) Hello(ctx context.Context, req *Request, rsp *Response) error {
rsp.Message = "Hello " + req.Name
return nil
}
func main() {
// create the service
service := micro.New("helloworld")
// initialise service
service.Init()
// register handler
service.Handle(new(Say))
// run the service
service.Run()
}
Now run the service
go run main.go
Take a note of the address with the log line
Transport [http] Listening on [::]:35823
Now you can call the service
curl -XPOST \
-H 'Content-Type: application/json' \
-H 'Micro-Endpoint: Say.Hello' \
-d '{"name": "alice"}' \
http://localhost:35823
To set a fixed address, pass it as an option:
service := micro.New("helloworld", micro.Address(":8080"))
Alternatively use MICRO_SERVER_ADDRESS=:8080 as an env var
curl -XPOST \
-H 'Content-Type: application/json' \
-H 'Micro-Endpoint: Say.Hello' \
-d '{"name": "alice"}' \
http://localhost:8080
If you want to define services with protobuf you can use protoc-gen-micro (go-micro.dev/v5/cmd/protoc-gen-micro).
Install the generator:
go install go-micro.dev/v5/cmd/[email protected]
Note: Use a specific version instead of
@latestto avoid module path conflicts. See releases for the latest version.
cd helloworld
mkdir proto
Edit a file proto/helloworld.proto
syntax = "proto3";
package greeter;
option go_package = "/proto;helloworld";
service Say {
rpc Hello(Request) returns (Response) {}
}
message Request {
string name = 1;
}
message Response {
string message = 1;
}
You can now generate a client/server like so (ensure $GOBIN is on your $PATH so protoc can find protoc-gen-micro):
protoc --proto_path=. --micro_out=. --go_out=. helloworld.proto
In your main.go update the code to reference the generated code
package main
import (
"go-micro.dev/v5"
pb "github.com/micro/helloworld/proto"
)
type Say struct{}
func (h *Say) Hello(ctx context.Context, req *pb.Request, rsp *pb.Response) error {
rsp.Message = "Hello " + req.Name
return nil
}
func main() {
// create the service
service := micro.New("helloworld")
// initialise service
service.Init()
// register handler
pb.RegisterSayHandler(service.Server(), &Say{})
// run the service
service.Run()
}
Now I can run this again
go run main.go
The generated code provides us a client
package main
import (
"context"
"fmt"
"go-micro.dev/v5"
pb "github.com/micro/helloworld/proto"
)
func main() {
service := micro.New("helloworld")
service.Init()
say := pb.NewSayService("helloworld", service.Client())
rsp, err := say.Hello(context.TODO(), &pb.Request{
Name: "John",
})
if err != nil {
fmt.Println(err)
return
}
fmt.Println(rsp.Message)
}
Install the Micro CLI:
go install go-micro.dev/v5/cmd/[email protected]
Note: Use a specific version instead of
@latestto avoid module path conflicts. See releases for the latest version.
Call a running service via RPC:
micro call helloworld Say.Hello '{"name": "John"}'
Alternative using the dynamic CLI commands:
micro helloworld say hello --name="John"
Every core interface has a matching command, so you can inspect and manipulate the registry, broker, store, and config from the terminal:
# Registry — service discovery
micro registry list # list services
micro registry get helloworld # nodes + endpoints
micro registry watch # stream registration events
# Broker — pub/sub
micro broker subscribe events # stream messages from a topic
micro broker publish events 'hello' # publish a message
# Store — persistence
micro store list # list keys
micro store write greeting hello # write a record
micro store read greeting # read it back
micro store delete greeting # delete it
# Config — dynamic configuration (from environment)
micro config get database.host # reads DATABASE_HOST
micro config dump # print all config
These mirror the registry, broker, store, and config packages — the same interfaces your services use, exposed on the CLI.