0
# Command-Line Interface
1

2
Interactive and batch STOMP client providing comprehensive command-line access to all stomp.py functionality including message sending, subscription management, transaction handling, and broker connectivity testing.
3

4
## Capabilities
5

6
### Interactive Client
7

8
Command-line STOMP client with interactive shell for real-time broker interaction.
9

10
```python { .api }
11
def main():
12
    """
13
    Launch interactive STOMP CLI client.
14
    
15
    Usage:
16
    python -m stomp [options]
17
    
18
    Options:
19
    --host HOST: broker hostname (default: localhost)
20
    --port PORT: broker port (default: 61613) 
21
    --user USER: authentication username
22
    --password PASS: authentication password
23
    --ssl: enable SSL/TLS connection
24
    --ssl-key-file FILE: SSL private key file
25
    --ssl-cert-file FILE: SSL certificate file
26
    --ssl-ca-certs FILE: SSL CA certificates file
27
    --listen DEST: listen-only mode for destination
28
    --file FILE: execute commands from file
29
    --version: show version information
30
    """
31

32
class StompCLI(Cmd, ConnectionListener):
33
    """
34
    Interactive STOMP command processor.
35
    
36
    Provides command-line interface for STOMP operations
37
    with connection management, message handling, and 
38
    transaction support.
39
    """
40
```
41

42
### Connection Commands
43

44
Connection management and broker interaction commands.
45

46
```python { .api }
47
def do_connect(self, args):
48
    """
49
    Connect to STOMP broker.
50
    
51
    Usage: connect [username] [password]
52
    
53
    Parameters:
54
    - username: str, authentication username (optional)
55
    - password: str, authentication password (optional)
56
    
57
    Examples:
58
    connect
59
    connect admin secret
60
    connect user@domain.com mypassword
61
    """
62

63
def do_disconnect(self, args):
64
    """
65
    Disconnect from STOMP broker.
66
    
67
    Usage: disconnect [receipt-id]
68
    
69
    Parameters:
70
    - receipt-id: str, receipt ID for disconnect confirmation (optional)
71
    """
72

73
def do_stats(self, args):
74
    """
75
    Display connection statistics.
76
    
77
    Usage: stats
78
    
79
    Shows:
80
    - Connection count and status
81
    - Messages sent/received counters
82
    - Error count and heartbeat statistics
83
    - Timing information
84
    """
85
```
86

87
### Message Operations
88

89
Message sending, receiving, and destination management.
90

91
```python { .api }
92
def do_send(self, args):
93
    """
94
    Send message to destination.
95
    
96
    Usage: send <destination> <message>
97
    
98
    Parameters:
99
    - destination: str, target queue or topic (required)
100
    - message: str, message body content (required)
101
    
102
    Examples:
103
    send /queue/test Hello World
104
    send /topic/events {"type": "notification", "data": "value"}
105
    """
106

107
def do_sendrec(self, args):
108
    """
109
    Send message and wait for receipt confirmation.
110
    
111
    Usage: sendrec <destination> <message>
112
    
113
    Parameters:
114
    - destination: str, target queue or topic (required)  
115
    - message: str, message body content (required)
116
    
117
    Waits for receipt confirmation before returning.
118
    """
119

120
def do_sendreply(self, args):
121
    """
122
    Send message with reply-to header.
123
    
124
    Usage: sendreply <destination> <reply-to> <message>
125
    
126
    Parameters:
127
    - destination: str, target queue or topic (required)
128
    - reply-to: str, reply destination (required)
129
    - message: str, message body content (required)
130
    """
131

132
def do_sendfile(self, args):
133
    """
134
    Send file contents as message body.
135
    
136
    Usage: sendfile <destination> <filename>
137
    
138
    Parameters:
139
    - destination: str, target queue or topic (required)
140
    - filename: str, path to file to send (required)
141
    
142
    Reads entire file content and sends as message body.
143
    """
144
```
145

146
### Subscription Management
147

148
Queue and topic subscription with acknowledgment handling.
149

150
```python { .api }
151
def do_subscribe(self, args):
152
    """
153
    Subscribe to destination for message delivery.
154
    
155
    Usage: subscribe <destination> [ack-mode] [subscription-id]
156
    
157
    Parameters:
158
    - destination: str, queue or topic to subscribe to (required)
159
    - ack-mode: str, acknowledgment mode (auto|client|client-individual)
160
    - subscription-id: str, unique subscription identifier
161
    
162
    Examples:
163
    subscribe /queue/orders
164
    subscribe /topic/events auto sub-1
165
    subscribe /queue/work client work-subscription
166
    """
167

168
def do_unsubscribe(self, args):
169
    """
170
    Unsubscribe from destination.
171
    
172
    Usage: unsubscribe <destination|subscription-id>
173
    
174
    Parameters:
175
    - destination: str, destination to unsubscribe from
176
    - subscription-id: str, subscription ID to cancel
177
    
178
    Examples:
179
    unsubscribe /queue/orders
180
    unsubscribe sub-1
181
    """
182

183
def do_ack(self, args):
184
    """
185
    Acknowledge message processing.
186
    
187
    Usage: ack <message-id> [subscription-id]
188
    
189
    Parameters:
190
    - message-id: str, ID of message to acknowledge (required)
191
    - subscription-id: str, subscription identifier (optional)
192
    
193
    Used with 'client' and 'client-individual' ack modes.
194
    """
195

196
def do_nack(self, args):
197
    """
198
    Negative acknowledge message (STOMP 1.1+).
199
    
200
    Usage: nack <message-id> [subscription-id]
201
    
202
    Parameters:
203
    - message-id: str, ID of message to nack (required)
204
    - subscription-id: str, subscription identifier (optional)
205
    
206
    Signals processing failure, may trigger redelivery.
207
    """
208
```
209

210
### Transaction Support
211

212
Atomic transaction management for grouped operations.
213

214
```python { .api }
215
def do_begin(self, args):
216
    """
217
    Begin transaction.
218
    
219
    Usage: begin [transaction-id]
220
    
221
    Parameters:
222
    - transaction-id: str, unique transaction identifier (optional)
223
    
224
    If no transaction-id provided, generates unique ID.
225
    """
226

227
def do_commit(self, args):
228
    """
229
    Commit transaction.
230
    
231
    Usage: commit [transaction-id]
232
    
233
    Parameters:
234
    - transaction-id: str, transaction to commit (optional)
235
    
236
    Commits current transaction if no ID specified.
237
    """
238

239
def do_abort(self, args):
240
    """
241
    Abort transaction.
242
    
243
    Usage: abort [transaction-id]
244
    
245
    Parameters:
246
    - transaction-id: str, transaction to abort (optional)
247
    
248
    Aborts current transaction if no ID specified.
249
    """
250
```
251

252
### Utility Commands
253

254
Debugging, information, and control commands.
255

256
```python { .api }
257
def do_run(self, args):
258
    """
259
    Execute commands from file.
260
    
261
    Usage: run <filename>
262
    
263
    Parameters:
264
    - filename: str, path to command file (required)
265
    
266
    Executes each line as CLI command.
267
    Command file format: one command per line.
268
    """
269

270
def do_version(self, args):
271
    """
272
    Display version information.
273
    
274
    Usage: version
275
    
276
    Shows stomp.py library version and build information.
277
    """
278

279
def do_quit(self, args):
280
    """
281
    Exit CLI client.
282
    
283
    Usage: quit
284
    
285
    Cleanly disconnects and exits interactive session.
286
    """
287
```
288

289
## Usage Examples
290

291
### Interactive Mode
292

293
```bash
294
# Start interactive client
295
python -m stomp --host broker.example.com --port 61613
296

297
# Inside interactive session:
298
(Cmd) connect admin password
299
(Cmd) subscribe /queue/orders auto
300
(Cmd) send /queue/orders {"order_id": 12345, "item": "widget"}
301
(Cmd) stats
302
(Cmd) disconnect
303
(Cmd) quit
304
```
305

306
### SSL Connection
307

308
```bash
309
# Connect with SSL/TLS
310
python -m stomp \
311
    --host secure-broker.com \
312
    --port 61614 \
313
    --ssl \
314
    --ssl-key-file /path/to/client.key \
315
    --ssl-cert-file /path/to/client.crt \
316
    --ssl-ca-certs /path/to/ca.crt \
317
    --user client_user \
318
    --password client_pass
319
```
320

321
### Listen-Only Mode
322

323
```bash
324
# Listen to destination without interaction
325
python -m stomp \
326
    --host broker.com \
327
    --port 61613 \
328
    --user monitor \
329
    --password secret \
330
    --listen /topic/events
331
```
332

333
### Batch Command Execution
334

335
```bash
336
# Execute commands from file
337
python -m stomp \
338
    --host broker.com \
339
    --port 61613 \
340
    --user automation \
341
    --password script_pass \
342
    --file /path/to/commands.txt
343
```
344

345
**Example commands.txt:**
346
```
347
connect
348
subscribe /queue/batch-work client work-sub
349
send /queue/notifications Batch job started
350
begin batch-tx-001
351
send /queue/process-items Process item A
352
send /queue/process-items Process item B  
353
commit batch-tx-001
354
unsubscribe work-sub
355
disconnect
356
```
357

358
### Authentication Examples
359

360
```bash
361
# Basic authentication
362
python -m stomp --host broker.com --user myuser --password mypass
363

364
# Domain authentication
365
python -m stomp --host broker.com --user user@domain.com --password pass
366

367
# Empty credentials (guest access)
368
python -m stomp --host broker.com --user "" --password ""
369
```
370

371
### Advanced Configuration
372

373
```bash
374
# Custom heartbeats and timeouts
375
python -m stomp \
376
    --host broker.com \
377
    --port 61613 \
378
    --heartbeats 10000,10000 \
379
    --timeout 30.0 \
380
    --user client \
381
    --password secret
382
```
383

384
### Integration Patterns
385

386
#### Shell Scripting
387

388
```bash
389
#!/bin/bash
390
# Send notification via STOMP
391

392
echo "send /queue/alerts System maintenance starting" | \
393
python -m stomp \
394
    --host monitoring.com \
395
    --port 61613 \
396
    --user alerting \
397
    --password $ALERT_PASSWORD \
398
    --file -
399
```
400

401
#### Monitoring Script
402

403
```bash
404
#!/bin/bash
405
# Monitor queue activity
406

407
python -m stomp \
408
    --host broker.com \
409
    --port 61613 \
410
    --user monitor \
411
    --password $MONITOR_PASS \
412
    --listen /queue/system-events > events.log &
413

414
STOMP_PID=$!
415
sleep 3600  # Monitor for 1 hour
416
kill $STOMP_PID
417
```
418

419
#### Configuration File Usage
420

421
**config.txt:**
422
```
423
# Connection setup
424
connect admin secretpassword
425

426
# Setup subscriptions  
427
subscribe /queue/orders client order-processor
428
subscribe /topic/events auto event-monitor
429

430
# Send startup notification
431
send /topic/system {"service": "processor", "status": "started"}
432

433
# Keep connection alive (comment to auto-exit)
434
# quit
435
```
436

437
```bash
438
python -m stomp --host broker.com --file config.txt
439
```