0
# CLI Interface
1

2
Full command-line interface with extensive options, magic syntax, and multiple output formats. The CLI provides both traditional piped input processing and direct command execution capabilities.
3

4
## CLI Entry Point
5

6
```python { .api }
7
def main() -> None:
8
    """
9
    Main CLI entry point function.
10
    
11
    Handles argument parsing, command execution, and output formatting.
12
    Called when running 'jc' command or 'python -m jc'.
13
    """
14
```
15

16
## CLI Class
17

18
The main CLI handler class that manages all command-line operations.
19

20
```python { .api }
21
class JcCli:
22
    """
23
    Main CLI interface class handling argument parsing and command execution.
24
    """
25
    
26
    def __init__(self) -> None:
27
        """
28
        Initialize CLI handler with default settings.
29
        
30
        Sets up internal state for:
31
        - Input/output data handling
32
        - Parser module management  
33
        - Formatting and display options
34
        - Command execution options
35
        """
36
```
37

38
## Package Information Class
39

40
```python { .api }
41
class info:
42
    """Package metadata and version information."""
43
    
44
    version: str = "1.25.5"
45
    description: str = "JSON Convert"
46
    author: str = "Kelly Brazil"
47
    author_email: str = "kellyjonbrazil@gmail.com"
48
    website: str = "https://github.com/kellyjonbrazil/jc"
49
    copyright: str = "© 2019-2025 Kelly Brazil"
50
    license: str = "MIT License"
51
```
52

53
## Command-Line Usage Patterns
54

55
### Basic Parsing (Pipe Mode)
56

57
```bash
58
# Parse command output via pipe
59
command | jc --parser-name
60

61
# Examples
62
dig example.com | jc --dig
63
ps aux | jc --ps
64
netstat -rn | jc --netstat
65
```
66

67
### Magic Syntax (Direct Execution)
68

69
```bash
70
# Execute commands directly with jc
71
jc command [arguments]
72

73
# Examples  
74
jc dig example.com
75
jc ps aux
76
jc netstat -rn
77
jc ls -la /etc
78
```
79

80
### Parser Selection
81

82
```bash
83
# Use specific parser
84
jc --dig dig example.com
85
jc --ps ps aux
86

87
# List available parsers
88
jc -a
89
jc --about
90

91
# Get parser documentation
92
jc -h --dig
93
jc --help --ps
94
```
95

96
## Output Format Options
97

98
### JSON Output (Default)
99

100
```bash
101
# Standard JSON output
102
jc dig example.com
103

104
# Pretty-printed JSON
105
jc -p dig example.com
106
jc --pretty dig example.com
107

108
# Raw (preprocessed) JSON
109
jc -r dig example.com  
110
jc --raw dig example.com
111
```
112

113
### Alternative Formats
114

115
```bash
116
# YAML output
117
jc -y dig example.com
118
jc --yaml dig example.com
119

120
# Monochrome output (no colors)
121
jc -m dig example.com
122
jc --monochrome dig example.com
123

124
# Force color output
125
jc -C dig example.com
126
jc --force-color dig example.com
127
```
128

129
## Streaming Options
130

131
```bash
132
# Use streaming parser
133
tail -f /var/log/syslog | jc --syslog-s
134

135
# Stream with error handling
136
tail -f /var/log/messages | jc --syslog-s --ignore-exceptions
137

138
# Unbuffer output for real-time processing
139
tail -f access.log | jc --clf-s --unbuffer
140
```
141

142
## Advanced Options
143

144
### Slicing and Filtering
145

146
```bash
147
# Slice output (Python slice syntax)
148
jc dig example.com -s '[0]'        # First element
149
jc ps aux -s '[0:5]'               # First 5 elements
150
jc ls -la -s '[-3:]'               # Last 3 elements
151

152
# Combine with external tools
153
jc ps aux | jq '.[] | select(.command | contains("python"))'
154
```
155

156
### Debugging and Verbosity
157

158
```bash
159
# Quiet mode (suppress warnings)
160
jc -q dig example.com
161
jc --quiet dig example.com
162

163
# Debug mode
164
jc -d dig example.com
165
jc --debug dig example.example
166

167
# Verbose debug
168
jc -dd dig example.com
169
jc --debug --debug dig example.com
170
```
171

172
### Batch Processing
173

174
```bash
175
# Slurp mode (combine multiple JSON outputs into array)
176
# Only available for parsers that support slurping
177
cat file1.json file2.json | jc --slurp --json
178

179
# Process multiple files
180
for file in *.csv; do
181
    cat "$file" | jc --csv > "${file%.csv}.json"
182
done
183
```
184

185
## Parser-Specific Options
186

187
Many parsers accept additional options passed through the CLI:
188

189
```bash
190
# Examples of parser-specific options
191
jc --csv --delimiter=';' < data.csv
192
jc --ini --duplicate-keys < config.ini
193
jc --timestamp --format='%Y-%m-%d %H:%M:%S' < timestamps.txt
194
```
195

196
## Shell Completions
197

198
### Bash Completion
199

200
```bash
201
# Generate bash completion script  
202
jc --bash-completion
203

204
# Install completion
205
jc --bash-completion > /etc/bash_completion.d/jc
206
```
207

208
### Zsh Completion
209

210
```bash
211
# Generate zsh completion script
212
jc --zsh-completion
213

214
# Install completion  
215
jc --zsh-completion > ~/.zsh/completions/_jc
216
```
217

218
## Integration Examples
219

220
### Script Integration
221

222
```bash
223
#!/bin/bash
224
# Extract specific data from system commands
225

226
# Get total memory from free command
227
total_mem=$(jc free -h | jq -r '.[] | select(.type=="Mem") | .total')
228

229
# Get running processes count
230
process_count=$(jc ps aux | jq 'length')
231

232
# Get disk usage over 80%
233
high_usage=$(jc df -h | jq '.[] | select(.use_percent > 80) | .filesystem')
234

235
echo "Total Memory: $total_mem"
236
echo "Running Processes: $process_count"  
237
echo "High Disk Usage: $high_usage"
238
```
239

240
### Log Analysis Pipeline
241

242
```bash
243
# Real-time log analysis
244
tail -f /var/log/nginx/access.log | \
245
  jc --clf-s | \
246
  jq -r 'select(.status_code >= 400) | "\(.date_time) \(.status_code) \(.request)"'
247
```
248

249
### System Monitoring
250

251
```bash  
252
# Monitor system metrics
253
watch -n 5 'jc ps aux | jq "sort_by(.percent_cpu) | reverse | .[0:5] | .[] | \"\(.percent_cpu)% \(.command)\""'
254
```
255

256
## Error Handling
257

258
The CLI provides comprehensive error handling and user feedback:
259

260
```bash
261
# Invalid parser
262
jc --invalid-parser command
263
# Error: "invalid-parser" is not found or is not a valid parser module.
264

265
# Missing input
266
jc --dig
267
# Error: No input data
268

269
# Parser-specific errors
270
echo "invalid data" | jc --json
271
# Warning: JSON parser error (with --quiet suppresses warnings)
272
```
273

274
## Exit Codes
275

276
- `0` - Successful execution
277
- `100` - General error (invalid arguments, parser errors, etc.)
278
- `101-255` - Parser-specific error codes
279

280
## Environment Variables
281

282
```bash
283
# Customize jc behavior via environment variables
284
export JC_COLORS="red,green,blue"  # Custom color scheme
285
export JC_INDENT=4                 # Default JSON indentation
286
export JC_QUIET=1                  # Default quiet mode
287
```