0
# Command Line Interface
1

2
Command-line tool for resolving module paths from the terminal. The CLI provides a convenient way to test module resolution and debug resolution issues without writing JavaScript code.
3

4
## Capabilities
5

6
### Resolve Command
7

8
Main command-line interface for module resolution.
9

10
```bash { .api }
11
resolve <specifier> [--preserve-symlinks]
12
```
13

14
**Parameters:**
15
- `<specifier>` - The module specifier to resolve (required)
16
- `--preserve-symlinks` - Enable symlink preservation mode (optional)
17

18
**Usage Examples:**
19

20
```bash
21
# Resolve a package from node_modules
22
resolve lodash
23
# Output: /path/to/node_modules/lodash/index.js
24

25
# Resolve a relative path
26
resolve ./lib/utils
27
# Output: /current/directory/lib/utils.js
28

29
# Resolve with symlink preservation
30
resolve my-package --preserve-symlinks
31
# Output: /path/with/symlinks/preserved
32

33
# Resolve a core module
34
resolve fs
35
# Output: fs
36

37
# Resolve a scoped package
38
resolve @babel/core
39
# Output: /path/to/node_modules/@babel/core/lib/index.js
40
```
41

42
## Installation and Usage
43

44
### Global Installation
45

46
```bash
47
npm install -g resolve
48
resolve <specifier>
49
```
50

51
### Local Installation
52

53
```bash
54
npm install resolve
55
npx resolve <specifier>
56
```
57

58
### Project Scripts
59

60
Add to package.json:
61

62
```json
63
{
64
  "scripts": {
65
    "resolve": "resolve"
66
  }
67
}
68
```
69

70
Then use:
71

72
```bash
73
npm run resolve <specifier>
74
```
75

76
## Options
77

78
### Preserve Symlinks
79

80
The `--preserve-symlinks` option enables symlink preservation mode, equivalent to setting `preserveSymlinks: true` in the JavaScript API. This flag is only available when the Node.js version supports it.
81

82
```bash { .api }
83
resolve <specifier> --preserve-symlinks
84
```
85

86
**Examples:**
87

88
```bash
89
# Normal resolution (default)
90
resolve my-lib
91
# May resolve symlinks in the path
92

93
# With symlink preservation
94
resolve my-lib --preserve-symlinks
95
# Keeps symlinks intact in the resolved path
96
```
97

98
This option is particularly useful when working with:
99
- npm link'd packages
100
- Monorepos with symlinked dependencies
101
- Development environments with symlinked modules
102

103
## Resolution Context
104

105
The CLI tool resolves modules relative to the current working directory, equivalent to:
106

107
```javascript
108
const resolve = require('resolve');
109
resolve.sync(specifier, { basedir: process.cwd() });
110
```
111

112
### Working Directory
113

114
```bash
115
# Resolve from current directory
116
cd /my/project
117
resolve lodash
118
# Searches for lodash starting from /my/project
119

120
# Same as above but explicit
121
resolve lodash --basedir=/my/project  # (Not supported - use cd instead)
122
```
123

124
## Exit Codes
125

126
The CLI tool uses standard exit codes to indicate success or failure:
127

128
```bash { .api }
129
# Exit codes:
130
# 0 - Success (module resolved)
131
# 1 - Invalid usage or command error  
132
# 2 - Resolution error or unknown argument
133
```
134

135
**Examples:**
136

137
```bash
138
# Successful resolution
139
resolve fs
140
echo $?  # 0
141

142
# Module not found
143
resolve nonexistent-module
144
echo $?  # 2
145

146
# Invalid usage
147
resolve
148
echo $?  # 1
149

150
# Unknown argument
151
resolve fs --unknown-flag
152
echo $?  # 2
153
```
154

155
## Error Handling
156

157
### Module Not Found
158

159
```bash
160
$ resolve nonexistent-module
161
Error: Cannot find module 'nonexistent-module' from '/current/directory'
162
$ echo $?
163
2
164
```
165

166
### Invalid Usage
167

168
```bash
169
$ resolve
170
Error: `resolve` expects a specifier
171
$ echo $?
172
2
173
```
174

175
### Unknown Arguments
176

177
```bash
178
$ resolve fs --unknown-flag
179
Unknown argument --unknown-flag
180
$ echo $?
181
2
182
```
183

184
### Security Restrictions
185

186
The CLI tool includes security checks to ensure it's being run directly as an executable:
187

188
```bash
189
# These will work:
190
resolve fs
191
npx resolve fs
192
./node_modules/.bin/resolve fs
193

194
# Direct execution is required - the tool validates its execution context
195
```
196

197
## Integration Examples
198

199
### Shell Scripts
200

201
```bash
202
#!/bin/bash
203

204
# Check if a module exists before using it
205
if resolve lodash >/dev/null 2>&1; then
206
  echo "lodash is available"
207
  node -e "console.log(require('lodash').version)"
208
else
209
  echo "lodash not found - installing..."
210
  npm install lodash
211
fi
212
```
213

214
### Build Scripts
215

216
```bash
217
# Verify all dependencies can be resolved
218
for dep in lodash express react; do
219
  if ! resolve "$dep" >/dev/null 2>&1; then
220
    echo "Error: $dep cannot be resolved"
221
    exit 1
222
  fi
223
done
224
echo "All dependencies resolved successfully"
225
```
226

227
### Development Debugging
228

229
```bash
230
# Debug resolution issues
231
resolve my-problematic-module
232
# See exactly where the module resolves to
233

234
# Compare with and without symlink preservation
235
resolve linked-module
236
resolve linked-module --preserve-symlinks
237
```
238

239
## Platform Support
240

241
The CLI tool works on all platforms supported by Node.js:
242
- Linux
243
- macOS  
244
- Windows
245

246
On Windows, both forward slashes and backslashes in paths are handled correctly:
247

248
```bash
249
# Windows examples
250
resolve ./lib\utils  # Works
251
resolve ./lib/utils  # Also works
252
```