go-micro.dev/v5@v5.12.0/cmd/micro/cli/README.md (about) 1 # Micro [](https://opensource.org/licenses/Apache-2.0) 2 3 A Go microservices toolkit 4 5 ## Overview 6 7 Micro is a toolkit for Go microservices development. It provides the foundation for building services in the cloud. 8 The core of Micro is the [Go Micro](https://github.com/micro/go-micro) framework, which developers import and use in their code to 9 write services. Surrounding this we introduce a number of tools to make it easy to serve and consume services. 10 11 ## Install the CLI 12 13 Install `micro` via `go install` 14 15 ``` 16 go install go-micro.dev/v5@latest 17 ``` 18 19 Or via install script 20 21 ``` 22 wget -q https://raw.githubusercontent.com/micro/micro/master/scripts/install.sh -O - | /bin/bash 23 ``` 24 25 For releases see the [latest](https://go-micro.dev/releases/latest) tag 26 27 ## Create a service 28 29 Create your service (all setup is now automatic!): 30 31 ``` 32 micro new helloworld 33 ``` 34 35 This will: 36 - Create a new service in the `helloworld` directory 37 - Automatically run `go mod tidy` and `make proto` for you 38 - Show the updated project tree including generated files 39 - Warn you if `protoc` is not installed, with install instructions 40 41 ## Run the service 42 43 Run the service 44 45 ``` 46 micro run 47 ``` 48 49 List services to see it's running and registered itself 50 51 ``` 52 micro services 53 ``` 54 55 ## Describe the service 56 57 Describe the service to see available endpoints 58 59 ``` 60 micro describe helloworld 61 ``` 62 63 Output 64 65 ``` 66 { 67 "name": "helloworld", 68 "version": "latest", 69 "metadata": null, 70 "endpoints": [ 71 { 72 "request": { 73 "name": "Request", 74 "type": "Request", 75 "values": [ 76 { 77 "name": "name", 78 "type": "string", 79 "values": null 80 } 81 ] 82 }, 83 "response": { 84 "name": "Response", 85 "type": "Response", 86 "values": [ 87 { 88 "name": "msg", 89 "type": "string", 90 "values": null 91 } 92 ] 93 }, 94 "metadata": {}, 95 "name": "Helloworld.Call" 96 }, 97 { 98 "request": { 99 "name": "Context", 100 "type": "Context", 101 "values": null 102 }, 103 "response": { 104 "name": "Stream", 105 "type": "Stream", 106 "values": null 107 }, 108 "metadata": { 109 "stream": "true" 110 }, 111 "name": "Helloworld.Stream" 112 } 113 ], 114 "nodes": [ 115 { 116 "metadata": { 117 "broker": "http", 118 "protocol": "mucp", 119 "registry": "mdns", 120 "server": "mucp", 121 "transport": "http" 122 }, 123 "id": "helloworld-31e55be7-ac83-4810-89c8-a6192fb3ae83", 124 "address": "127.0.0.1:39963" 125 } 126 ] 127 } 128 ``` 129 130 ## Call the service 131 132 Call via RPC endpoint 133 134 ``` 135 micro call helloworld Helloworld.Call '{"name": "Asim"}' 136 ``` 137 138 ## Create a client 139 140 Create a client to call the service 141 142 ```go 143 package main 144 145 import ( 146 "context" 147 "fmt" 148 149 "go-micro.dev/v5" 150 ) 151 152 type Request struct { 153 Name string 154 } 155 156 type Response struct { 157 Message string 158 } 159 160 func main() { 161 client := micro.New("helloworld").Client() 162 163 req := client.NewRequest("helloworld", "Helloworld.Call", &Request{Name: "John"}) 164 165 var rsp Response 166 167 err := client.Call(context.TODO(), req, &rsp) 168 if err != nil { 169 fmt.Println(err) 170 return 171 } 172 173 fmt.Println(rsp.Message) 174 } 175 ``` 176 177 ## Protobuf 178 179 Use protobuf for code generation with [protoc-gen-micro](https://go-micro.dev/tree/master/cmd/protoc-gen-micro) 180 181 ## Server 182 183 The micro server is an api and web dashboard that provide a fixed entrypoint for seeing and querying services. 184 185 Run it like so 186 187 ``` 188 micro server 189 ``` 190 191 Then browse to [localhost:8080](http://localhost:8080) 192 193 ### API Endpoints 194 195 The API provides a fixed HTTP entrypoint for calling services 196 197 ``` 198 curl http://localhost:8080/api/helloworld/Helloworld/Call -d '{"name": "John"}' 199 ``` 200 See /api for more details and documentation for each service 201 202 ### Web Dashboard 203 204 The web dashboard provides a modern, secure UI for managing and exploring your Micro services. Major features include: 205 206 - **Dynamic Service & Endpoint Forms**: Browse all registered services and endpoints. For each endpoint, a dynamic form is generated for easy testing and exploration. 207 - **API Documentation**: The `/api` page lists all available services and endpoints, with request/response schemas and a sidebar for quick navigation. A documentation banner explains authentication requirements. 208 - **JWT Authentication**: All login and token management uses a custom JWT utility. Passwords are securely stored with bcrypt. All `/api/x` endpoints and authenticated pages require an `Authorization: Bearer <token>` header (or `micro_token` cookie as fallback). 209 - **Token Management**: The `/auth/tokens` page allows you to generate, view (obfuscated), and copy JWT tokens. Tokens are stored and can be revoked. When a user is deleted, all their tokens are revoked immediately. 210 - **User Management**: The `/auth/users` page allows you to create, list, and delete users. Passwords are never shown or stored in plaintext. 211 - **Token Revocation**: JWT tokens are stored and checked for revocation on every request. Revoked or deleted tokens are immediately invalidated. 212 - **Security**: All protected endpoints use consistent authentication logic. Unauthorized or revoked tokens receive a 401 error. All sensitive actions require authentication. 213 - **Logs & Status**: View service logs and status (PID, uptime, etc) directly from the dashboard. 214 215 To get started, run: 216 217 ``` 218 micro server 219 ``` 220 221 Then browse to [localhost:8080](http://localhost:8080) and log in with the default admin account (`admin`/`micro`). 222 223 > **Note:** See the `/api` page for details on API authentication and how to generate tokens for use with the HTTP API