0
# CLI Interface
1

2
Command-line interface for running, managing, and interacting with nameko services in development and production environments.
3

4
## Capabilities
5

6
### Main CLI Command
7

8
The `nameko` command provides the primary interface for service management and development tasks.
9

10
```bash { .api }
11
nameko <command> [options]
12
```
13

14
**Available Commands:**
15

16
- `run` - Run nameko services
17
- `shell` - Interactive shell for testing services
18
- `show-config` - Display service configuration
19
- `backdoor` - Start backdoor server for debugging
20

21
### Running Services
22

23
Start one or more nameko services from Python modules.
24

25
```bash { .api }
26
nameko run <module>[:<ServiceClass>] [options]
27

28
Options:
29
  --config <file>          Configuration file path
30
  --broker <url>           AMQP broker URL  
31
  --backdoor-port <port>   Enable backdoor on specified port
32
  --rlimits <limits>       Set resource limits
33
```
34

35
**Usage Examples:**
36

37
```bash
38
# Run all services from a module
39
nameko run myproject.services
40

41
# Run specific service class
42
nameko run myproject.services:UserService
43

44
# Run with custom configuration
45
nameko run myproject.services --config config.yaml
46

47
# Run with custom broker
48
nameko run myproject.services --broker amqp://guest:guest@localhost:5672//
49

50
# Run multiple services
51
nameko run myproject.user_service myproject.email_service
52

53
# Run with backdoor for debugging
54
nameko run myproject.services --backdoor-port 3000
55

56
# Run with resource limits
57
nameko run myproject.services --rlimits "nofile=10000,nproc=500"
58
```
59

60
### Interactive Shell
61

62
Start an interactive Python shell with RPC proxy for testing services.
63

64
```bash { .api }
65
nameko shell [options]
66

67
Options:
68
  --config <file>     Configuration file path
69
  --broker <url>      AMQP broker URL
70
  --interface <type>  Shell interface ('bpython', 'ipython', 'plain')
71
```
72

73
**Usage Examples:**
74

75
```bash
76
# Start interactive shell
77
nameko shell
78

79
# Shell with custom configuration
80
nameko shell --config config.yaml
81

82
# Shell with custom broker
83
nameko shell --broker amqp://guest:guest@localhost:5672//
84

85
# Use specific shell interface
86
nameko shell --interface ipython
87
```
88

89
**Shell Environment:**
90

91
When you start the nameko shell, the following objects are available:
92

93
```python
94
# Available in shell namespace
95
n           # RPC proxy cluster for calling services  
96
config      # Current configuration
97
make_proxy  # Function to create RPC proxies
98

99
# Example usage in shell
100
>>> n.user_service.get_user(123)
101
{'id': 123, 'name': 'John Doe'}
102

103
>>> n.email_service.send_email('user@example.com', 'Hello!')
104
{'status': 'sent'}
105

106
# Create custom proxy with timeout
107
>>> proxy = make_proxy('user_service', timeout=10)
108
>>> proxy.get_user(456)
109
```
110

111
### Configuration Display
112

113
Show the resolved configuration for services.
114

115
```bash { .api }
116
nameko show-config [options]
117

118
Options:
119
  --config <file>     Configuration file path
120
  --format <format>   Output format ('yaml', 'json')
121
```
122

123
**Usage Examples:**
124

125
```bash
126
# Show default configuration
127
nameko show-config
128

129
# Show configuration from file
130
nameko show-config --config production.yaml
131

132
# Output as JSON
133
nameko show-config --format json
134

135
# Output as YAML (default)
136
nameko show-config --format yaml
137
```
138

139
### Backdoor Server
140

141
Start a backdoor server for runtime debugging and inspection.
142

143
```bash { .api }
144
nameko backdoor [options]
145

146
Options:
147
  --config <file>      Configuration file path
148
  --backdoor-port <port>  Port for backdoor server (default: 3000)
149
```
150

151
**Usage Examples:**
152

153
```bash
154
# Start backdoor on default port
155
nameko backdoor
156

157
# Start on custom port
158
nameko backdoor --backdoor-port 8000
159

160
# Connect to backdoor
161
telnet localhost 3000
162
```
163

164
**Backdoor Environment:**
165

166
The backdoor provides access to:
167

168
```python
169
# Available in backdoor namespace
170
services    # Dictionary of running service containers
171
config      # Service configuration
172
n           # RPC proxy cluster
173
```
174

175
### Configuration Files
176

177
Configuration can be provided via YAML or JSON files.
178

179
**YAML Configuration Example:**
180

181
```yaml
182
# config.yaml
183
AMQP_URI: "amqp://guest:guest@localhost:5672//"
184
WEB_SERVER_ADDRESS: "0.0.0.0:8000"
185

186
# Service-specific configuration
187
DATABASE_URL: "postgresql://user:pass@localhost/mydb"
188
REDIS_URL: "redis://localhost:6379/0"
189

190
# Logging configuration
191
LOGGING:
192
  version: 1
193
  handlers:
194
    console:
195
      class: logging.StreamHandler
196
      level: INFO
197
  root:
198
    level: INFO
199
    handlers: [console]
200

201
# Custom service settings
202
EMAIL_SETTINGS:
203
  smtp_host: "smtp.gmail.com"
204
  smtp_port: 587
205
  use_tls: true
206
```
207

208
**JSON Configuration Example:**
209

210
```json
211
{
212
  "AMQP_URI": "amqp://guest:guest@localhost:5672//",
213
  "WEB_SERVER_ADDRESS": "0.0.0.0:8000",
214
  "DATABASE_URL": "postgresql://user:pass@localhost/mydb",
215
  "MAX_WORKERS": 10,
216
  "RPC_TIMEOUT": 30
217
}
218
```
219

220
### Environment Variables
221

222
Configuration values can be overridden with environment variables.
223

224
```bash
225
# Set AMQP broker via environment
226
export AMQP_URI="amqp://user:pass@broker-host:5672//"
227

228
# Set web server address
229
export WEB_SERVER_ADDRESS="0.0.0.0:8080"
230

231
# Set custom configuration
232
export DATABASE_URL="postgresql://localhost/production_db"
233

234
# Run with environment variables
235
nameko run myproject.services
236
```
237

238
### Development Workflow
239

240
Common CLI patterns for development.
241

242
```bash
243
# Development server with auto-reload (using external tools)
244
watchmedo auto-restart --directory=./myproject --pattern=*.py --recursive -- nameko run myproject.services
245

246
# Run services with debugging
247
nameko run myproject.services --backdoor-port 3000
248

249
# Test services interactively
250
nameko shell --config dev-config.yaml
251

252
# Check configuration
253
nameko show-config --config dev-config.yaml
254

255
# Production deployment
256
nameko run myproject.services --config production.yaml --rlimits "nofile=65536"
257
```
258

259
### Logging and Monitoring
260

261
CLI options for logging and service monitoring.
262

263
```bash
264
# Run with verbose logging
265
NAMEKO_LOG_LEVEL=DEBUG nameko run myproject.services
266

267
# Log to file
268
nameko run myproject.services 2>&1 | tee service.log
269

270
# Run with structured logging
271
nameko run myproject.services --config logging-config.yaml
272
```
273

274
**Logging Configuration:**
275

276
```yaml
277
# logging-config.yaml
278
LOGGING:
279
  version: 1
280
  formatters:
281
    default:
282
      format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
283
    json:
284
      format: '{"timestamp": "%(asctime)s", "service": "%(name)s", "level": "%(levelname)s", "message": "%(message)s"}'
285
  handlers:
286
    console:
287
      class: logging.StreamHandler
288
      formatter: default
289
      level: INFO
290
    file:
291
      class: logging.FileHandler
292
      filename: service.log
293
      formatter: json
294
      level: DEBUG
295
  loggers:
296
    nameko:
297
      level: INFO
298
      handlers: [console, file]
299
  root:
300
    level: WARNING
301
    handlers: [console]
302
```
303

304
### Process Management
305

306
CLI patterns for production process management.
307

308
```bash
309
# Run as daemon (using external process manager)
310
nohup nameko run myproject.services --config production.yaml &
311

312
# With systemd service
313
systemctl start nameko-services
314
systemctl enable nameko-services
315

316
# With supervisor
317
supervisorctl start nameko-services
318

319
# Docker deployment
320
docker run -d --name nameko-services \
321
  -v /path/to/config.yaml:/config.yaml \
322
  myproject:latest \
323
  nameko run myproject.services --config /config.yaml
324

325
# Kubernetes deployment
326
kubectl apply -f nameko-deployment.yaml
327
```
328

329
### Health Checks and Monitoring
330

331
CLI commands for service health monitoring.
332

333
```bash
334
# Basic health check via shell
335
echo "n.health_service.check()" | nameko shell --config production.yaml
336

337
# Monitor service metrics
338
nameko shell --config production.yaml
339
>>> n.metrics_service.get_stats()
340

341
# Check service discovery
342
nameko shell
343
>>> # List available services by trying to call them
344
>>> import inspect
345
>>> for service in ['user_service', 'email_service', 'order_service']:
346
...     try:
347
...         print(f"{service}: {getattr(n, service).ping()}")
348
...     except Exception as e:
349
...         print(f"{service}: ERROR - {e}")
350
```
351

352
### Troubleshooting
353

354
Common CLI debugging techniques.
355

356
```bash
357
# Check configuration issues
358
nameko show-config --config problematic.yaml
359

360
# Debug with backdoor
361
nameko run myproject.services --backdoor-port 3000
362
# Connect: telnet localhost 3000
363

364
# Verbose logging for debugging
365
NAMEKO_LOG_LEVEL=DEBUG nameko run myproject.services
366

367
# Test individual service methods
368
nameko shell
369
>>> n.problematic_service.test_method()
370

371
# Check AMQP connectivity
372
nameko shell --broker amqp://test-broker:5672//
373
>>> n  # Should connect or show error
374
```