0
# Command Line Interface
1
2
Erdantic provides a comprehensive command-line interface for generating entity relationship diagrams from fully qualified model or module names. The CLI supports various output formats, styling options, and configuration parameters.
3
4
## CLI Entry Points
5
6
```bash
7
# Primary command
8
erdantic [models_or_modules...] --out OUTPUT_FILE [options]
9
10
# Alternative module invocation
11
python -m erdantic [models_or_modules...] --out OUTPUT_FILE [options]
12
```
13
14
## Command Arguments and Options
15
16
```python { .api }
17
# Main CLI function signature
18
def main(
19
models_or_modules: list[str],
20
out: Path,
21
terminal_models: list[str] = [],
22
termini: list[str] = [],
23
limit_search_models_to: list[str] = [],
24
dot: bool = False,
25
no_overwrite: bool = False,
26
quiet: int = 0,
27
verbose: int = 0,
28
list_plugins: Optional[bool] = False,
29
version: Optional[bool] = None,
30
):
31
"""Draw entity relationship diagrams (ERDs) for Python data model classes. Diagrams are
32
rendered using the Graphviz library. Currently supported data modeling frameworks are Pydantic,
33
attrs, and standard library dataclasses.
34
"""
35
```
36
37
### Required Arguments
38
39
- **`models_or_modules`** - One or more full dotted paths for data model classes, or modules containing data model classes to include in diagram (e.g., `'erdantic.examples.pydantic.Party'`)
40
41
### Required Options
42
43
- **`--out`, `-o`** - Output filename for the diagram (format inferred from extension)
44
45
### Optional Arguments
46
47
- **`--terminal-model`, `-t`** - Full dotted paths for data model classes to set as terminal nodes. Can be repeated for multiple models
48
- **`--terminus`** - (Deprecated) Use `--terminal-model` instead
49
- **`--limit-search-models-to`, `-m`** - Plugin identifiers to limit model search to specific types. Can be repeated
50
- **`--dot`, `-d`** - Print DOT language representation to console instead of rendering image
51
- **`--no-overwrite`** - Prevent overwriting existing output files
52
- **`--quiet`, `-q`** - Decrease log verbosity (can be used multiple times)
53
- **`--verbose`, `-v`** - Increase log verbosity (can be used multiple times)
54
- **`--list-plugins`** - List active plugins and exit
55
- **`--version`** - Show erdantic version and exit
56
57
## Usage Examples
58
59
### Basic Diagram Generation
60
61
```bash
62
# Generate diagram from specific model classes
63
erdantic my.models.User my.models.Post --out models.png
64
65
# Generate diagram from an entire module
66
erdantic my.models --out module_diagram.svg
67
```
68
69
### Output Formats
70
71
```bash
72
# Different output formats (inferred from extension)
73
erdantic my.models --out diagram.png # PNG image
74
erdantic my.models --out diagram.svg # SVG vector
75
erdantic my.models --out diagram.pdf # PDF document
76
erdantic my.models --out diagram.eps # EPS format
77
```
78
79
### DOT Language Output
80
81
```bash
82
# Generate DOT language representation instead of image
83
erdantic my.models --dot
84
85
# Save DOT to file for external processing
86
erdantic my.models --dot > models.dot
87
```
88
89
### Terminal Models (Stopping Points)
90
91
```bash
92
# Stop analysis at specific models to control diagram complexity
93
erdantic my.models --terminal-model my.base.BaseEntity --out simplified.png
94
95
# Multiple terminal models
96
erdantic my.models \
97
--terminal-model my.base.BaseEntity \
98
--terminal-model my.shared.CommonMixin \
99
--out controlled.png
100
```
101
102
### Plugin Filtering
103
104
```bash
105
# Limit to specific model types only
106
erdantic my.models --limit-search-models-to pydantic --out pydantic_only.png
107
108
# Multiple plugin types
109
erdantic my.models \
110
--limit-search-models-to pydantic \
111
--limit-search-models-to dataclasses \
112
--out filtered.png
113
```
114
115
### Logging Control
116
117
```bash
118
# Quiet operation (suppress most logging)
119
erdantic my.models --out quiet.png --quiet
120
121
# Very quiet (suppress almost all logging)
122
erdantic my.models --out very_quiet.png -qq
123
124
# Verbose logging (show debug information)
125
erdantic my.models --out debug.png --verbose
126
127
# Very verbose logging
128
erdantic my.models --out very_debug.png -vv
129
```
130
131
### File Safety
132
133
```bash
134
# Prevent accidental overwriting
135
erdantic my.models --out existing.png --no-overwrite
136
# This will fail if existing.png already exists
137
```
138
139
### Information Commands
140
141
```bash
142
# Show version
143
erdantic --version
144
145
# List available plugins
146
erdantic --list-plugins
147
```
148
149
## Advanced Examples
150
151
### Complex Project Analysis
152
153
```bash
154
# Analyze multiple modules with terminal models and filtering
155
erdantic \
156
my.user.models \
157
my.post.models \
158
my.comment.models \
159
--terminal-model my.base.TimestampedModel \
160
--terminal-model my.base.SoftDeleteModel \
161
--limit-search-models-to pydantic \
162
--out complex_project.svg \
163
--verbose
164
```
165
166
### Integration with Build Scripts
167
168
```bash
169
#!/bin/bash
170
# Generate documentation diagrams for CI/CD
171
172
# Check if output is up to date
173
if [ "models.png" -ot "my/models.py" ]; then
174
echo "Regenerating model diagram..."
175
erdantic my.models --out models.png --no-overwrite || {
176
echo "Failed to generate diagram"
177
exit 1
178
}
179
fi
180
```
181
182
### Batch Processing
183
184
```bash
185
# Generate diagrams for multiple modules
186
for module in user post comment admin; do
187
erdantic "my.${module}.models" --out "${module}_models.png"
188
done
189
190
# Generate both image and DOT versions
191
erdantic my.models --out models.svg
192
erdantic my.models --dot > models.dot
193
```
194
195
## Error Handling
196
197
### Common Error Scenarios
198
199
```bash
200
# Module not found
201
erdantic nonexistent.module --out error.png
202
# Error: Unable to import 'nonexistent.module'
203
204
# Output directory doesn't exist
205
erdantic my.models --out /nonexistent/dir/diagram.png
206
# Error: Output directory does not exist
207
208
# File exists with --no-overwrite
209
erdantic my.models --out existing.png --no-overwrite
210
# Error: existing.png already exists, and you specified --no-overwrite
211
212
# Unsupported model type
213
erdantic my.unsupported.models --out error.png
214
# Error: Model type not supported, available plugins: [...]
215
```
216
217
### Exit Codes
218
219
- **0** - Success
220
- **1** - General error (file exists with --no-overwrite, import failures, etc.)
221
222
## Environment Integration
223
224
225
### IDE Integration
226
227
Many IDEs can be configured to run erdantic automatically:
228
229
```json
230
// VS Code task example (.vscode/tasks.json)
231
{
232
"version": "2.0.0",
233
"tasks": [
234
{
235
"label": "Generate ERD",
236
"type": "shell",
237
"command": "erdantic",
238
"args": ["${workspaceFolder}/models", "--out", "docs/erd.png"],
239
"group": "build"
240
}
241
]
242
}
243
```
244
245
## Module Import Utility
246
247
```python { .api }
248
def import_object_from_name(full_obj_name: str) -> Union[ModuleType, object]:
249
"""Import an object from a fully qualified name.
250
251
Args:
252
full_obj_name (str): Fully qualified name of object or module to import.
253
254
Returns:
255
Union[ModuleType, object]: The imported module or object.
256
257
Raises:
258
ModelOrModuleNotFoundError: If the module or object cannot be imported.
259
"""
260
```
261
262
This utility function is used internally by the CLI to resolve the string arguments into actual Python objects, but can also be used programmatically for dynamic imports.
263
264
### Usage Examples
265
266
```python
267
from erdantic.cli import import_object_from_name
268
269
# Import a module
270
my_module = import_object_from_name("my.models")
271
272
# Import a specific class
273
MyModel = import_object_from_name("my.models.MyModel")
274
275
# Import a function
276
my_function = import_object_from_name("my.utils.helper_function")
277
```