0
# Command Line Interface
1

2
CLI binary for running microservices with support for multiple endpoint types and configuration options. The `micro` command provides flexible deployment options for containerized and traditional environments.
3

4
## Capabilities
5

6
### Micro CLI Command
7

8
Main binary for running microservice files with flexible endpoint configuration and automatic file discovery.
9

10
```bash { .api }
11
micro [options] [entry_point.js]
12

13
# Default behavior - listens on port 3000, uses package.json main or index.js
14
micro
15

16
# Specify entry point file
17
micro ./my-service.js
18

19
# Custom port
20
micro -l tcp://0.0.0.0:8080
21

22
# Multiple endpoints
23
micro -l tcp://0.0.0.0:3000 -l unix:/tmp/micro.sock
24

25
# Environment variable port with fallback
26
micro -l tcp://0.0.0.0:${PORT-3000}
27
```
28

29
### Command Options
30

31
```bash { .api }
32
Options:
33
  --help                    Show help message and usage information
34
  -v, --version            Display current version of micro
35
  -l, --listen <uri>       Specify listen URI (can be used multiple times)
36
```
37

38
### Endpoint Types
39

40
Micro supports three types of endpoints for different deployment scenarios:
41

42
```bash { .api }
43
# TCP endpoints (traditional host:port)
44
micro -l tcp://hostname:port
45
micro -l tcp://0.0.0.0:3000
46
micro -l tcp://localhost:8080
47

48
# UNIX domain sockets (for inter-process communication)
49
micro -l unix:/path/to/socket.sock
50
micro -l unix:/tmp/microservice.sock
51

52
# Windows named pipes (Windows environments)
53
micro -l pipe:\\.\pipe\PipeName
54
micro -l pipe:\\.\pipe\MicroService
55
```
56

57
**Usage Examples:**
58

59
```bash
60
# Basic usage - default port 3000
61
micro
62

63
# Production server with custom port
64
micro -l tcp://0.0.0.0:8080 ./app.js
65

66
# Development with environment variable
67
export PORT=3001
68
micro -l tcp://0.0.0.0:$PORT
69

70
# Multiple listening endpoints
71
micro -l tcp://0.0.0.0:3000 -l unix:/tmp/api.sock ./service.js
72

73
# Container deployment
74
micro -l tcp://0.0.0.0:${PORT-3000} ./dist/server.js
75

76
# Local development with specific file
77
micro ./my-microservice.js
78

79
# Windows named pipe
80
micro -l pipe:\\.\pipe\MyAPIService ./api.js
81
```
82

83
### Entry Point Discovery
84

85
When no entry point file is specified, micro follows this discovery order:
86

87
1. **package.json main field**: Uses the `main` property from package.json
88
2. **index.js fallback**: Uses index.js in current directory if no main field
89
3. **Error handling**: Exits with error if no valid entry point found
90

91
```bash { .api }
92
# These commands follow the discovery process:
93
micro                    # Uses package.json main or index.js
94
micro -l tcp://0.0.0.0:8080  # Same discovery with custom port
95
```
96

97
**Example package.json configurations:**
98

99
```json
100
{
101
  "name": "my-service",
102
  "main": "./dist/server.js",
103
  "scripts": {
104
    "start": "micro",
105
    "dev": "micro ./src/dev-server.js"
106
  }
107
}
108
```
109

110
### Environment Integration
111

112
```bash
113
# Using environment variables for configuration
114
export PORT=8080
115
export HOST=0.0.0.0
116
micro -l tcp://$HOST:$PORT
117

118
# Docker container usage
119
FROM node:16
120
WORKDIR /app
121
COPY . .
122
RUN npm install
123
EXPOSE 3000
124
CMD ["micro", "-l", "tcp://0.0.0.0:3000"]
125

126
# Kubernetes deployment
127
apiVersion: apps/v1
128
kind: Deployment
129
spec:
130
  template:
131
    spec:
132
      containers:
133
      - name: microservice
134
        image: my-service:latest
135
        command: ["micro", "-l", "tcp://0.0.0.0:8080"]
136
        ports:
137
        - containerPort: 8080
138
```
139

140
### Process Management
141

142
The CLI includes built-in process management features:
143

144
- **Graceful shutdown**: Handles SIGINT and SIGTERM signals with cleanup
145
- **Error handling**: Logs startup errors with helpful error codes to https://err.sh/micro/
146
- **Port binding**: Automatically handles port binding errors and validation
147
- **File validation**: Validates entry point files exist and are readable
148
- **Module loading**: Uses dynamic imports with ES6 module support and fallback handling
149
- **Export validation**: Ensures the loaded module exports a function as the request handler
150

151
```bash
152
# The CLI handles these scenarios automatically:
153
micro ./non-existent.js     # Error: The file or directory "non-existent.js" doesn't exist!
154
micro ./invalid-module.js   # Error: The file "invalid-module.js" does not export a function.
155
micro -l tcp://0.0.0.0:80   # Error: permission denied (if not root)
156
micro -l invalid://test      # Error: Unknown --listen endpoint scheme (protocol): invalid:
157
```
158

159
**Error Handling Behavior:**
160
- All CLI errors are logged to stderr with descriptive messages
161
- Error URLs point to https://err.sh/micro/{error-code} for additional help
162
- Module import errors include full stack traces for debugging
163
- Process exits with code 1 for startup failures, code 2 for usage errors
164

165
### Integration Examples
166

167
#### Docker Compose
168

169
```yaml
170
version: '3.8'
171
services:
172
  api:
173
    build: .
174
    command: micro -l tcp://0.0.0.0:3000
175
    ports:
176
      - "3000:3000"
177
    environment:
178
      - NODE_ENV=production
179

180
  worker:
181
    build: .
182
    command: micro -l unix:/tmp/worker.sock ./worker.js
183
    volumes:
184
      - /tmp:/tmp
185
```
186

187
#### Systemd Service
188

189
```ini
190
[Unit]
191
Description=Micro API Service
192
After=network.target
193

194
[Service]
195
Type=simple
196
User=microservice
197
WorkingDirectory=/opt/microservice
198
ExecStart=/usr/bin/node /usr/local/bin/micro -l tcp://0.0.0.0:3000
199
Restart=always
200
RestartSec=10
201

202
[Install]
203
WantedBy=multi-user.target
204
```
205

206
#### Process Manager (PM2)
207

208
```json
209
{
210
  "apps": [{
211
    "name": "micro-api",
212
    "script": "/usr/local/bin/micro",
213
    "args": ["-l", "tcp://0.0.0.0:3000", "./api.js"],
214
    "instances": 4,
215
    "exec_mode": "cluster",
216
    "env": {
217
      "NODE_ENV": "production"
218
    }
219
  }]
220
}
221
```
222

223
#### Nginx Reverse Proxy
224

225
```nginx
226
upstream microservice {
227
    server unix:/tmp/micro.sock;
228
}
229

230
server {
231
    listen 80;
232
    server_name api.example.com;
233
    
234
    location / {
235
        proxy_pass http://microservice;
236
        proxy_set_header Host $host;
237
        proxy_set_header X-Real-IP $remote_addr;
238
    }
239
}
240
```