0
# Command Line Interface
1

2
Ontospy provides comprehensive command-line tools for interactive ontology exploration, analysis, and documentation generation. The CLI interface includes commands for scanning ontologies, generating documentation, managing local libraries, and launching interactive shells.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
The primary command-line interface providing access to all ontospy functionality.
9

10
```python { .api }
11
def main_cli():
12
    """
13
    Main CLI entry point handling command routing and argument parsing.
14
    
15
    Available commands:
16
    - scan: Analyze RDF sources and display statistics
17
    - gendocs: Generate documentation and visualizations  
18
    - lib: Manage local ontology library
19
    - shell: Launch interactive Python shell
20
    - ser: Serialize RDF data to different formats
21
    - utils: Utility functions and tools
22
    """
23
```
24

25
**Command Line Usage:**
26
```bash
27
# Basic usage
28
ontospy [command] [options] [arguments]
29

30
# Show help
31
ontospy --help
32
ontospy [command] --help
33

34
# Quick test utility
35
ontospy_quicktest
36
```
37

38
### Scan Command
39

40
Analyze RDF sources and generate comprehensive reports about ontological content and structure.
41

42
```python { .api }
43
def scan():
44
    """
45
    Scan and analyze RDF sources with detailed reporting.
46
    
47
    Supports:
48
    - Local files and directories
49
    - Remote URLs and SPARQL endpoints
50
    - Multiple RDF formats
51
    - Statistical analysis and summaries
52
    - Entity enumeration and relationship mapping
53
    """
54
```
55

56
**Usage Examples:**
57
```bash
58
# Scan local ontology file
59
ontospy scan ontology.owl
60

61
# Scan remote ontology
62
ontospy scan http://xmlns.com/foaf/0.1/
63

64
# Scan with verbose output
65
ontospy scan --verbose ontology.rdf
66

67
# Scan SPARQL endpoint  
68
ontospy scan --endpoint http://dbpedia.org/sparql
69

70
# Output raw RDF data
71
ontospy scan --raw ontology.ttl
72

73
# Include individuals in analysis
74
ontospy scan --individuals ontology.owl
75

76
# Specify RDF format
77
ontospy scan --format turtle data.rdf
78
```
79

80
### Documentation Generation Command
81

82
Generate comprehensive documentation and visualizations from ontologies.
83

84
```python { .api }
85
def gendocs():
86
    """
87
    Generate ontology documentation and visualizations.
88
    
89
    Features:
90
    - Multiple output formats (HTML, markdown, interactive)
91
    - Customizable themes and styling
92
    - Interactive visualization types
93
    - Batch processing capabilities
94
    - Template customization options
95
    """
96
```
97

98
**Usage Examples:**
99
```bash
100
# Generate default HTML documentation
101
ontospy gendocs ontology.owl
102

103
# Specify output directory
104
ontospy gendocs ontology.owl --outputdir ./docs
105

106
# Use specific visualization type
107
ontospy gendocs ontology.owl --type 2  # HTML multi-page
108

109
# Apply custom theme
110
ontospy gendocs ontology.owl --theme flatly
111

112
# Set custom title
113
ontospy gendocs ontology.owl --title "My Ontology"
114

115
# Interactive type selection
116
ontospy gendocs ontology.owl --interactive
117

118
# Generate multiple formats
119
ontospy gendocs ontology.owl --type 1,2,3  # HTML single, multi, markdown
120
```
121

122
### Library Management
123

124
Manage local ontology repositories with caching, indexing, and quick access functionality.
125

126
```python { .api }
127
def lib():
128
    """
129
    Manage local ontology library and cache.
130
    
131
    Operations:
132
    - Initialize local repository
133
    - Cache frequently used ontologies  
134
    - List cached ontologies with metadata
135
    - Search and filter library contents
136
    - Update and refresh cached data
137
    - Remove outdated cache entries
138
    """
139
```
140

141
**Usage Examples:**
142
```bash
143
# Initialize local library
144
ontospy lib --init
145

146
# List cached ontologies
147
ontospy lib --list
148

149
# Search library contents
150
ontospy lib --search "foaf"
151

152
# Add ontology to library
153
ontospy lib --add http://xmlns.com/foaf/0.1/
154

155
# Remove from library  
156
ontospy lib --remove "foaf"
157

158
# Update cached ontology
159
ontospy lib --update http://xmlns.com/foaf/0.1/
160

161
# Show library statistics
162
ontospy lib --stats
163

164
# Clear library cache
165
ontospy lib --clear
166
```
167

168
### Interactive Shell
169

170
Launch enhanced Python shell environment with ontospy preloaded and ontology-specific utilities.
171

172
```python { .api }
173
def shell():
174
    """
175
    Launch interactive Python shell with ontospy environment.
176
    
177
    Features:
178
    - Preloaded ontospy modules and classes
179
    - Ontology-specific helper functions
180
    - Enhanced tab completion for ontology exploration
181
    - Built-in documentation and examples
182
    - Quick access to common analysis patterns
183
    """
184
```
185

186
**Usage Examples:**
187
```bash
188
# Launch interactive shell
189
ontospy shell
190

191
# Launch with preloaded ontology
192
ontospy shell ontology.owl
193

194
# Shell with remote ontology
195
ontospy shell http://xmlns.com/foaf/0.1/
196

197
# Launch with specific namespace preferences
198
ontospy shell --lang en ontology.owl
199
```
200

201
**Shell Environment:**
202
```python
203
# Available in shell session
204
import ontospy
205

206
# Preloaded if ontology specified
207
g = ontospy.Ontospy("your-ontology.owl", build_all=True)
208

209
# Quick exploration commands
210
g.stats()  # Show statistics
211
g.printClassTree()  # Print class hierarchy
212
g.all_classes  # Access all classes
213
g.all_properties  # Access all properties
214

215
# Helper functions available
216
help(ontospy)  # Built-in help
217
examples()  # Show usage examples (if available)
218
```
219

220
### Serialization Utilities
221

222
Convert between RDF formats and generate serialized output with format validation.
223

224
```python { .api }
225
def ser():
226
    """
227
    Serialize RDF data between different formats.
228
    
229
    Supported formats:
230
    - Turtle (.ttl)
231
    - RDF/XML (.rdf, .xml)  
232
    - N-Triples (.nt)
233
    - N3 (.n3)
234
    - JSON-LD (.jsonld)
235
    - Trig (.trig)
236
    - NQuads (.nq)
237
    """
238
```
239

240
**Usage Examples:**
241
```bash
242
# Convert RDF/XML to Turtle
243
ontospy ser --input ontology.rdf --output ontology.ttl --format turtle
244

245
# Convert Turtle to JSON-LD
246
ontospy ser --input data.ttl --output data.jsonld --format json-ld
247

248
# Pretty-print RDF data
249
ontospy ser --input ontology.owl --format turtle --pretty
250

251
# Validate RDF syntax
252
ontospy ser --input data.rdf --validate
253

254
# Convert with base URI
255
ontospy ser --input ontology.ttl --output ontology.rdf --format xml --base http://example.org/
256
```
257

258
### Utility Functions
259

260
Additional utility commands for ontology development and maintenance workflows.
261

262
```python { .api }
263
def utils():
264
    """
265
    Utility functions for ontology development workflows.
266
    
267
    Available utilities:
268
    - Ontology validation and syntax checking
269
    - Namespace analysis and cleanup
270
    - Dead link detection for imported ontologies
271
    - Duplicate detection and cleanup
272
    - Performance profiling for large ontologies
273
    """
274
```
275

276
**Usage Examples:**
277
```bash
278
# Validate ontology syntax
279
ontospy utils --validate ontology.owl
280

281
# Check for dead imports
282
ontospy utils --check-imports ontology.owl
283

284
# Analyze namespace usage
285
ontospy utils --namespaces ontology.rdf
286

287
# Find duplicate definitions
288
ontospy utils --duplicates ontology.ttl
289

290
# Profile ontology loading performance
291
ontospy utils --profile ontology.owl
292
```
293

294
## Core Action Functions
295

296
The CLI commands are implemented using core action functions that can also be used programmatically.
297

298
```python { .api }
299
from ontospy.core.actions import action_analyze
300

301
def action_analyze(sources, endpoint=None, print_opts=False, 
302
                  verbose=False, extra=False, raw=False, 
303
                  individuals=False, format=""):
304
    """
305
    Core analysis function used by scan command.
306
    
307
    Parameters:
308
    - sources (list): List of RDF sources to analyze
309
    - endpoint (str): SPARQL endpoint URL  
310
    - print_opts (bool): Print analysis options
311
    - verbose (bool): Enable verbose output
312
    - extra (bool): Include extra analysis details
313
    - raw (bool): Output raw RDF data
314
    - individuals (bool): Include individual analysis
315
    - format (str): Specify RDF format
316
    
317
    Returns:
318
    Ontospy: Analyzed ontology graph object
319
    """
320
```
321

322
## Configuration and Environment
323

324
### Environment Variables
325

326
```bash
327
# Set default output directory
328
export ONTOSPY_OUTPUT_DIR=/path/to/docs
329

330
# Configure library location  
331
export ONTOSPY_LIBRARY=/path/to/library
332

333
# Set default theme
334
export ONTOSPY_DEFAULT_THEME=flatly
335

336
# Configure cache behavior
337
export ONTOSPY_CACHE_DISABLE=false
338
```
339

340
### Configuration Files
341

342
Ontospy looks for configuration in:
343
- `~/.ontospy/config.ini` - Global configuration
344
- `./ontospy.ini` - Project-specific configuration  
345
- Environment variables (highest priority)
346

347
## Complete CLI Workflow Example
348

349
```bash
350
# 1. Initialize local library
351
ontospy lib --init
352

353
# 2. Add frequently used ontologies to library
354
ontospy lib --add http://xmlns.com/foaf/0.1/
355
ontospy lib --add http://purl.org/dc/terms/
356

357
# 3. Analyze new ontology
358
ontospy scan my-ontology.owl --verbose
359

360
# 4. Generate comprehensive documentation
361
ontospy gendocs my-ontology.owl \\
362
  --outputdir ./docs \\
363
  --type 2 \\
364
  --theme cerulean \\
365
  --title "My Domain Ontology"
366

367
# 5. Launch interactive exploration
368
ontospy shell my-ontology.owl
369

370
# 6. Convert to different format
371
ontospy ser --input my-ontology.owl \\
372
           --output my-ontology.ttl \\
373
           --format turtle
374

375
# 7. Validate and check ontology
376
ontospy utils --validate my-ontology.owl
377
ontospy utils --check-imports my-ontology.owl
378
```
379

380
## Integration with Python Scripts
381

382
CLI functionality can be integrated into Python scripts and automation workflows.
383

384
```python
385
import subprocess
386
import ontospy
387

388
# Use CLI commands from Python
389
def analyze_ontology(file_path):
390
    result = subprocess.run([
391
        'ontospy', 'scan', file_path, '--verbose'
392
    ], capture_output=True, text=True)
393
    return result.stdout
394

395
# Or use core functions directly
396
from ontospy.core.actions import action_analyze
397

398
def analyze_programmatically(sources):
399
    g = action_analyze(sources, verbose=True)
400
    return g
401

402
# Generate docs programmatically
403
from ontospy.gendocs.actions import build_visualization
404

405
def generate_docs(ontology_path, output_dir):
406
    g = ontospy.Ontospy(ontology_path, build_all=True)
407
    build_visualization(g, viz_index=2, path=output_dir)
408
```