0
# Command Line Interface
1

2
Full-featured CLI for dependency analysis from the command line. Includes options for output formatting, filtering, and visualization.
3

4
## Installation
5

6
```bash
7
npm install -g madge
8
```
9

10
## Capabilities
11

12
### Basic Usage
13

14
```bash { .api }
15
madge [options] <src...>
16
```
17

18
The CLI accepts one or more source files or directories to analyze.
19

20
**Usage Examples:**
21

22
```bash
23
# Analyze single file
24
madge src/app.js
25

26
# Analyze multiple files
27
madge src/app.js src/utils.js
28

29
# Analyze directory
30
madge src/
31

32
# Analyze multiple directories
33
madge src/ lib/
34
```
35

36
### Dependency Analysis Options
37

38
Options for controlling what dependencies to analyze and include.
39

40
```bash { .api }
41
-b, --basedir <path>        # Base directory for resolving paths
42
-x, --exclude <regexp>      # Exclude modules using RegExp
43
--extensions <list>         # Comma separated string of valid file extensions
44
--include-npm              # Include shallow NPM modules
45
--require-config <file>    # Path to RequireJS config
46
--webpack-config <file>    # Path to webpack config  
47
--ts-config <file>         # Path to typescript config
48
```
49

50
**Usage Examples:**
51

52
```bash
53
# Set base directory
54
madge --basedir /project/root src/
55

56
# Exclude node_modules
57
madge --exclude '^node_modules' src/
58

59
# Include specific file extensions
60
madge --extensions js,jsx,ts,tsx src/
61

62
# Include NPM dependencies
63
madge --include-npm src/
64

65
# Use TypeScript config
66
madge --ts-config tsconfig.json src/
67
```
68

69
### Output Format Options
70

71
Options for controlling how results are displayed.
72

73
```bash { .api }
74
-j, --json                 # Output as JSON
75
-s, --summary             # Show dependency count summary
76
--no-color                # Disable color in output and image
77
--no-spinner              # Disable progress spinner
78
--warning                 # Show warnings about skipped files
79
--debug                   # Turn on debug output
80
```
81

82
**Usage Examples:**
83

84
```bash
85
# JSON output
86
madge --json src/
87

88
# Summary with counts
89
madge --summary src/
90

91
# Disable colors
92
madge --no-color src/
93

94
# Show warnings
95
madge --warning src/
96
```
97

98
### Dependency Analysis Operations
99

100
Options for specific types of dependency analysis.
101

102
```bash { .api }
103
-c, --circular            # Show circular dependencies
104
-d, --depends <name>      # Show module dependents
105
--orphans                # Show modules that no one is depending on
106
--leaves                 # Show modules that have no dependencies
107
--no-count               # Disable circular dependencies counting
108
```
109

110
**Usage Examples:**
111

112
```bash
113
# Find circular dependencies
114
madge --circular src/
115

116
# Find what depends on a specific module
117
madge --depends utils.js src/
118

119
# Find orphaned modules
120
madge --orphans src/
121

122
# Find leaf modules (no dependencies)
123
madge --leaves src/
124
```
125

126
### Graph Generation Options
127

128
Options for generating visual graphs and DOT output.
129

130
```bash { .api }
131
-i, --image <file>        # Write graph to file as an image
132
--dot                    # Show graph using the DOT language
133
-l, --layout <name>      # Layout engine to use for graph (dot/neato/fdp/sfdp/twopi/circo)
134
--rankdir <direction>    # Set the direction of the graph layout
135
```
136

137
**Usage Examples:**
138

139
```bash
140
# Generate SVG image
141
madge --image graph.svg src/
142

143
# Generate PNG image  
144
madge --image graph.png src/
145

146
# Generate DOT output
147
madge --dot src/ > graph.gv
148

149
# Use different layout engine
150
madge --layout neato --image graph.svg src/
151

152
# Change graph direction
153
madge --rankdir TB --image graph.svg src/
154

155
# Generate image with only circular dependencies
156
madge --circular --image circular.svg src/
157
```
158

159
### Input Sources
160

161
The CLI supports multiple input methods.
162

163
```bash { .api }
164
--stdin                   # Read predefined tree from STDIN
165
```
166

167
**Usage Example:**
168

169
```bash
170
# Pipe dependency tree via STDIN
171
echo '{"a.js": ["b.js"], "b.js": []}' | madge --stdin --json
172
```
173

174
## Configuration Files
175

176
Madge supports configuration via `.madgerc` or `package.json`.
177

178
### .madgerc Configuration
179

180
```json
181
{
182
  "fontSize": "10px",
183
  "graphVizOptions": {
184
    "G": {
185
      "rankdir": "LR"  
186
    }
187
  },
188
  "excludeRegExp": ["test", "spec"],
189
  "fileExtensions": ["js", "jsx", "ts", "tsx"]
190
}
191
```
192

193
### package.json Configuration
194

195
```json
196
{
197
  "name": "my-project",
198
  "madge": {
199
    "fontSize": "10px", 
200
    "backgroundColor": "#ffffff",
201
    "nodeColor": "#000000"
202
  }
203
}
204
```
205

206
## Exit Codes
207

208
The CLI uses standard exit codes:
209

210
- **0**: Success, no circular dependencies found
211
- **1**: Circular dependencies found (when using `--circular` option)
212
- **1**: Error during execution
213

214
## Output Examples
215

216
### Default Output
217

218
```
219
┌────────────────────┐
220
│ Dependency graph   │
221
└────────────────────┘
222

223
src/app.js
224
  src/utils.js
225
  src/api.js
226

227
src/api.js  
228
  src/config.js
229

230
src/utils.js
231
  (no dependencies)
232

233
src/config.js
234
  (no dependencies)
235

236
✔ Processed 4 files (12ms)
237
```
238

239
### JSON Output
240

241
```bash
242
madge --json src/
243
```
244

245
```json
246
{
247
  "src/app.js": ["src/utils.js", "src/api.js"],
248
  "src/api.js": ["src/config.js"], 
249
  "src/utils.js": [],
250
  "src/config.js": []
251
}
252
```
253

254
### Circular Dependencies Output
255

256
```bash
257
madge --circular src/
258
```
259

260
```
261
✖ Found 2 circular dependencies!
262

263
1) src/a.js > src/b.js > src/a.js
264
2) src/x.js > src/y.js > src/z.js > src/x.js
265
```
266

267
### Summary Output
268

269
```bash
270
madge --summary src/
271
```
272

273
```
274
┌─────────────────────────────────────┐
275
│ Dependency Summary                  │
276
├─────────────────────────────────────┤
277
│ Total files        │ 12             │
278
│ Total dependencies │ 23             │
279
│ Circular dependencies │ 2           │
280
│ Orphaned files     │ 1              │
281
└─────────────────────────────────────┘
282
```
283

284
## Requirements
285

286
- **Node.js**: Version 18 or higher
287
- **Graphviz**: Required for image generation (optional for other features)
288
  - Mac: `brew install graphviz`
289
  - Ubuntu: `apt-get install graphviz`