0
# Command Line Interface
1

2
The `gntp.cli` module provides a full-featured command-line interface for sending GNTP notifications from shell scripts, system automation, and interactive use. It supports all notification parameters and integrates with the configuration file system.
3

4
## Capabilities
5

6
### Command Line Parser
7

8
Comprehensive argument parser supporting all GNTP notification options with sensible defaults and configuration file integration.
9

10
```python { .api }
11
class ClientParser(OptionParser):
12
    """
13
    Command line argument parser for GNTP notifications.
14
    
15
    Extends Python's OptionParser with GNTP-specific options organized
16
    into logical groups: Network Options and Notification Options.
17
    """
18
    
19
    def __init__(self):
20
        """
21
        Initialize parser with all GNTP command line options.
22
        
23
        Creates option groups for network settings (host, port, password)
24
        and notification settings (title, message, priority, etc.).
25
        Reads default values from ~/.gntp configuration file.
26
        """
27
    
28
    def parse_args(self, args=None, values=None):
29
        """
30
        Parse command line arguments with GNTP-specific processing.
31
        
32
        Handles stdin input for messages, automatic title generation,
33
        and logging level configuration.
34
        
35
        Parameters:
36
        - args (list): Command line arguments (None for sys.argv)
37
        - values: Initial option values
38
        
39
        Returns:
40
        tuple: (parsed_options, message_text)
41
        """
42
```
43

44
### Main Entry Point
45

46
Primary function that orchestrates the complete notification workflow from command line arguments to GNTP transmission.
47

48
```python { .api }
49
def main():
50
    """
51
    Main entry point for GNTP command line interface.
52
    
53
    Parses command line arguments, creates GrowlNotifier instance,
54
    registers with Growl server, handles icon loading, and sends
55
    the notification. Exits with appropriate status codes on failure.
56
    
57
    Command Line Usage:
58
    gntp [options] [title words...]
59
    
60
    Exit Codes:
61
    - 0: Success
62
    - Non-zero: Error tuple from failed operation
63
    """
64
```
65

66
## Command Line Options
67

68
### Network Options
69

70
Control connection to Growl server:
71

72
- `-H, --host HOST`: Growl server hostname (default: localhost, or from ~/.gntp)
73
- `--port PORT`: Growl server port (default: 23053, or from ~/.gntp)  
74
- `-P, --password PASSWORD`: Network authentication password (default: None, or from ~/.gntp)
75

76
### Notification Options
77

78
Control notification appearance and behavior:
79

80
- `-n, --name APP_NAME`: Application name (default: 'Python GNTP Test Client')
81
- `-N, --notification TYPE`: Notification type name (default: 'Notification')
82
- `-t, --title TITLE`: Notification title (default: command line args or message preview)
83
- `-m, --message MESSAGE`: Notification message (default: read from stdin)
84
- `-p, --priority PRIORITY`: Priority level from -2 to 2 (default: 0)
85
- `-s, --sticky`: Make notification sticky (default: False)
86
- `--image PATH_OR_URL`: Icon for notification (file path or URL)
87
- `--callback URL`: Callback URL for notification clicks
88
- `-d, --identifier ID`: Coalescing identifier for grouping notifications
89

90
### General Options
91

92
- `-v, --verbose`: Increase verbosity (repeat for more verbose output)
93
- `--version`: Show version information
94

95
## Usage Examples
96

97
### Basic Notification
98

99
```bash
100
# Simple notification with stdin message
101
echo "Build completed successfully" | gntp -t "Build Status"
102

103
# Direct message without stdin
104
gntp -m "Server is back online" -t "System Alert"
105

106
# Using command line arguments as title
107
gntp "Deployment Finished" -m "Version 1.2.3 deployed to production"
108
```
109

110
### Network Configuration
111

112
```bash
113
# Send to remote Growl server
114
gntp -H growl.company.com -P mypassword -m "Remote notification"
115

116
# Use different port
117
gntp --host 192.168.1.100 --port 23054 -m "Custom port notification"
118
```
119

120
### Notification Customization
121

122
```bash
123
# High priority sticky notification
124
gntp -p 2 -s -m "Critical system error detected" -t "CRITICAL ALERT"
125

126
# Low priority info notification
127
gntp -p -1 -m "Background task completed" -t "Info"
128

129
# Custom application and notification names
130
gntp -n "Backup System" -N "Backup Complete" -m "Daily backup finished"
131
```
132

133
### Icons and Resources
134

135
```bash
136
# URL-based icon
137
gntp --image "http://example.com/success.png" -m "Operation successful"
138

139
# Local file icon
140
gntp --image "/path/to/warning.png" -m "Warning condition detected"
141

142
# File icon with other options
143
gntp --image ~/icons/error.png -t "Error" -p 2 -s -m "Critical failure"
144
```
145

146
### Callbacks and Coalescing
147

148
```bash
149
# Notification with callback URL
150
gntp --callback "http://example.com/details" -m "Click for details"
151

152
# Coalescing notifications (replace previous with same ID)
153
gntp -d "build-status" -m "Build started..."
154
gntp -d "build-status" -m "Build 50% complete..."  # Replaces previous
155
gntp -d "build-status" -m "Build finished!"        # Replaces previous
156
```
157

158
### Interactive Use
159

160
```bash
161
# Interactive message input
162
gntp -t "Manual Message"
163
# (Enter message, press Ctrl-D to send)
164

165
# Combine with other commands
166
date | gntp -t "Current Time"
167
uptime | gntp -t "System Status"
168
```
169

170
### Shell Scripting Examples
171

172
```bash
173
#!/bin/bash
174
# Backup notification script
175

176
gntp -n "Backup Script" -N "Backup Started" -m "Starting daily backup..."
177

178
if backup_command; then
179
    gntp -n "Backup Script" -N "Backup Success" -p 1 \
180
         --image ~/icons/success.png \
181
         -m "Backup completed successfully at $(date)"
182
else
183
    gntp -n "Backup Script" -N "Backup Failed" -p 2 -s \
184
         --image ~/icons/error.png \
185
         --callback "http://backup.company.com/logs" \
186
         -m "Backup failed! Check logs for details."
187
fi
188
```
189

190
### Configuration File Integration
191

192
Create `~/.gntp` configuration file:
193

194
```ini
195
[gntp]
196
hostname = notifications.company.com
197
password = enterprise-password
198
port = 23053
199
```
200

201
Then use CLI with automatic configuration:
202

203
```bash
204
# Automatically uses settings from ~/.gntp
205
gntp -m "Using enterprise notification server"
206

207
# Override specific settings while keeping others from config
208
gntp -H localhost -m "Use localhost instead of config server"
209
```
210

211
### Build System Integration
212

213
```bash
214
# Makefile integration
215
build-success:
216
	gntp -n "Build System" -N "Build Success" -p 1 \
217
	     -m "Project built successfully in $(shell date)"
218

219
build-failed:
220
	gntp -n "Build System" -N "Build Failed" -p 2 -s \
221
	     --callback "http://buildserver/logs" \
222
	     -m "Build failed. Click for logs."
223

224
# CI/CD pipeline integration
225
deploy-notify:
226
	gntp -n "CI/CD Pipeline" -N "Deploy Complete" \
227
	     --image "http://company.com/deploy-icon.png" \
228
	     -m "Version ${VERSION} deployed to ${ENVIRONMENT}"
229
```
230

231
### System Monitoring Scripts
232

233
```bash
234
#!/bin/bash
235
# Disk space monitor
236

237
USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')
238

239
if [ $USAGE -gt 90 ]; then
240
    gntp -n "System Monitor" -N "Disk Alert" -p 2 -s \
241
         -t "Disk Space Critical" \
242
         -m "Root filesystem is ${USAGE}% full"
243
elif [ $USAGE -gt 80 ]; then
244
    gntp -n "System Monitor" -N "Disk Warning" -p 1 \
245
         -t "Disk Space Warning" \
246
         -m "Root filesystem is ${USAGE}% full"
247
fi
248
```
249

250
## Error Handling
251

252
The CLI handles errors gracefully:
253

254
- **Network failures**: Exit with error tuple from underlying GNTP operations
255
- **Authentication failures**: Exit with authentication error details
256
- **Missing configuration**: Continues with built-in defaults, logs info message
257
- **Invalid arguments**: Shows usage help and exits
258
- **File not found** (for icons): Logs error and continues without icon
259
- **Keyboard interrupt**: Exits cleanly during stdin input
260

261
## Installation and Deployment
262

263
When installed via pip, the CLI is available as the `gntp` command:
264

265
```bash
266
pip install gntp
267
gntp --help
268
```
269

270
For development or custom installations, the CLI can be run as a module:
271

272
```bash
273
python -m gntp.cli --help
274
```
275

276
## Integration with Configuration API
277

278
The CLI automatically integrates with the `gntp.config` module:
279

280
- Reads default values from `~/.gntp` configuration file
281
- Command line arguments override configuration file values
282
- Missing configuration file is handled gracefully
283
- Supports all configuration options (hostname, password, port)
284

285
This enables enterprise deployments where all CLI usage automatically connects to the correct notification server without requiring command line arguments.