0
# @lerna/list
1

2
@lerna/list is a command-line tool and programmatic library for listing local packages in a Lerna monorepo. It provides multiple output formats (JSON, NDJSON, parseable, graph, columnified) and extensive filtering capabilities to help developers manage and inspect packages in multi-package repositories.
3

4
## Package Information
5

6
- **Package Name**: @lerna/list
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @lerna/list` or use via `lerna list`
10

11
## Core Imports
12

13
```typescript
14
// Import the factory function (default export)
15
import createListCommand from "@lerna/list";
16

17
// Import the ListCommand class
18
import { ListCommand } from "@lerna/list";
19

20
// Import the yargs command module
21
import command from "@lerna/list/command";
22
```
23

24
For CommonJS:
25

26
```javascript
27
// Default export (factory function)
28
const createListCommand = require("@lerna/list");
29

30
// Named export (ListCommand class)
31
const { ListCommand } = require("@lerna/list");
32

33
// Command module
34
const command = require("@lerna/list/command");
35
```
36

37
## Basic Usage
38

39
### Command Line Usage
40

41
```bash
42
# List all public packages
43
lerna list
44

45
# List with detailed information
46
lerna list --long
47

48
# List all packages including private ones
49
lerna list --all
50

51
# Output as JSON
52
lerna list --json
53

54
# List with dependency graph
55
lerna list --graph
56
```
57

58
### Programmatic Usage
59

60
```typescript
61
import createListCommand from "@lerna/list";
62

63
// Create a ListCommand instance
64
const listCommand = createListCommand(process.argv);
65

66
// The command will execute its lifecycle methods when constructed
67
// through the Lerna Command base class system
68
```
69

70
## Capabilities
71

72
### Factory Function
73

74
Creates a new ListCommand instance for programmatic execution.
75

76
```typescript { .api }
77
/**
78
 * Factory function that creates and returns a ListCommand instance
79
 * @param argv - Command line arguments array (process.argv format)
80
 * @returns ListCommand instance ready for execution
81
 */
82
function createListCommand(argv: NodeJS.Process["argv"]): ListCommand;
83
```
84

85
### ListCommand Class
86

87
Main command implementation providing package listing functionality.
88

89
```typescript { .api }
90
/**
91
 * Command class for listing packages in a Lerna monorepo
92
 * Extends the base Command class from @lerna/core
93
 */
94
class ListCommand extends Command {
95
  /** Command does not require git repository */
96
  readonly requiresGit: boolean;
97
  
98
  /** Private result storage for formatted output */
99
  private result: { text: string; count: number };
100
  
101
  /**
102
   * Initializes the command by filtering packages and formatting output
103
   * @returns Promise that resolves when initialization is complete
104
   */
105
  initialize(): Promise<void>;
106
  
107
  /**
108
   * Executes the command by outputting the formatted package list
109
   * and logging success message
110
   */
111
  execute(): void;
112
}
113
```
114

115
### Command Module
116

117
Yargs command module configuration for CLI integration.
118

119
```typescript { .api }
120
/**
121
 * Yargs command module for CLI integration
122
 */
123
interface CommandModule {
124
  /** Primary command name */
125
  command: "list";
126
  
127
  /** Command aliases for convenience */
128
  aliases: ["ls", "la", "ll"];
129
  
130
  /** Command description */
131
  describe: "List local packages";
132
  
133
  /**
134
   * Configures yargs with listable and filter options
135
   * @param yargs - Yargs instance to configure
136
   */
137
  builder(yargs: any): any;
138
  
139
  /**
140
   * Handles command execution by creating ListCommand instance
141
   * @param argv - Parsed command arguments
142
   */
143
  handler(argv: any): any;
144
}
145
```
146

147
## Command Options
148

149
### Output Format Options
150

151
- `--json`: Show information as JSON array with name, version, private status, and location
152
- `--ndjson`: Show information as newline-delimited JSON
153
- `--parseable` / `-p`: Show parseable output instead of columnified view
154
- `--graph`: Show dependency graph as JSON-formatted adjacency list
155

156
### Display Options
157

158
- `--all` / `-a`: Show private packages that are normally hidden
159
- `--long` / `-l`: Show extended information (version and location)
160
- `--toposort`: Sort packages in topological order instead of lexical by directory
161

162
### Filtering Options
163

164
- `--scope <glob>`: Include only packages with names matching the given glob pattern
165
- `--ignore <glob>`: Exclude packages with names matching the given glob pattern
166
- `--no-private`: Exclude packages marked as private in package.json
167
- `--since <ref>`: Only include packages changed since the specified git reference
168
- `--include-dependents`: Include all transitive dependents regardless of other filters
169
- `--exclude-dependents`: Exclude all transitive dependents when using --since
170
- `--include-dependencies`: Include all transitive dependencies regardless of other filters
171
- `--include-merged-tags`: Include tags from merged branches when using --since
172
- `--include-filtered-dependencies`: Include filtered dependencies in the result (deprecated, use --include-dependencies)
173
- `--include-filtered-dependents`: Include filtered dependents in the result (deprecated, use --include-dependents)
174

175
## Command Aliases
176

177
The list command supports several convenient aliases:
178

179
- `lerna list` / `lerna ls`: Standard package listing
180
- `lerna la`: Equivalent to `lerna list --all` (shows private packages)
181
- `lerna ll`: Equivalent to `lerna list --long` (shows detailed information)
182

183
## Output Formats
184

185
### Default Format (Columnified)
186

187
```
188
package-1
189
package-2
190
package-3
191
```
192

193
### Long Format (`--long`)
194

195
```
196
package-1 v1.0.0 packages/package-1
197
package-2 v1.0.0 packages/package-2
198
package-3 v1.0.0 packages/package-3
199
```
200

201
### JSON Format (`--json`)
202

203
```json
204
[
205
  {
206
    "name": "package-1",
207
    "version": "1.0.0",
208
    "private": false,
209
    "location": "/path/to/packages/package-1"
210
  },
211
  {
212
    "name": "package-2", 
213
    "version": "1.0.0",
214
    "private": false,
215
    "location": "/path/to/packages/package-2"
216
  }
217
]
218
```
219

220
### NDJSON Format (`--ndjson`)
221

222
```
223
{"name":"package-1","version":"1.0.0","private":false,"location":"/path/to/packages/package-1"}
224
{"name":"package-2","version":"1.0.0","private":false,"location":"/path/to/packages/package-2"}
225
```
226

227
### Parseable Format (`--parseable`)
228

229
Basic parseable output shows absolute paths:
230

231
```
232
/path/to/packages/package-1
233
/path/to/packages/package-2
234
```
235

236
With `--long`, parseable output includes name and version:
237

238
```
239
/path/to/packages/package-1:package-1:1.0.0
240
/path/to/packages/package-2:package-2:1.0.0
241
```
242

243
Private packages are marked with `PRIVATE` flag:
244

245
```
246
/path/to/packages/package-3:package-3:1.0.0:PRIVATE
247
```
248

249
### Graph Format (`--graph`)
250

251
Shows dependency relationships as an adjacency list:
252

253
```json
254
{
255
  "package-1": ["package-2"],
256
  "package-2": [],
257
  "package-3": ["package-1", "package-2"]
258
}
259
```
260

261
## Types
262

263
```typescript { .api }
264
/**
265
 * Base Command class from @lerna/core
266
 */
267
declare class Command {
268
  /** Command name derived from class name */
269
  name: string;
270
  
271
  /** Whether command is composed (called from other commands) */
272
  composed: boolean;
273
  
274
  /** Command options and configuration */
275
  options: any;
276
  
277
  /** Lerna project instance */
278
  project: Project;
279
  
280
  /** npmlog logger instance */
281
  logger: any;
282
  
283
  /** Package graph for the monorepo */
284
  packageGraph?: PackageGraph;
285
  
286
  /** Execution options */
287
  execOpts?: { cwd: string; maxBuffer?: number };
288
}
289

290
/**
291
 * Result object containing formatted output and count
292
 */
293
interface ListResult {
294
  /** Formatted text output */
295
  text: string;
296
  
297
  /** Number of packages found */
298
  count: number;
299
}
300

301
/**
302
 * Package representation from @lerna/core
303
 */
304
interface Package {
305
  /** Package name */
306
  name: string;
307
  
308
  /** Package version */
309
  version: string;
310
  
311
  /** Whether package is marked as private */
312
  private: boolean;
313
  
314
  /** Absolute path to package directory */
315
  location: string;
316
  
317
  /** Package dependencies */
318
  dependencies?: Record<string, string>;
319
  
320
  /** Package dev dependencies */
321
  devDependencies?: Record<string, string>;
322
  
323
  /** Package peer dependencies */
324
  peerDependencies?: Record<string, string>;
325
  
326
  /** Package optional dependencies */
327
  optionalDependencies?: Record<string, string>;
328
}
329

330
/**
331
 * Options interface for listable formatting
332
 */
333
interface ListableOptions {
334
  /** Show as JSON array */
335
  json?: boolean;
336
  
337
  /** Show as newline-delimited JSON */
338
  ndjson?: boolean;
339
  
340
  /** Show all packages including private */
341
  all?: boolean;
342
  
343
  /** Show extended information */
344
  long?: boolean;
345
  
346
  /** Show parseable output */
347
  parseable?: boolean;
348
  
349
  /** Sort topologically */
350
  toposort?: boolean;
351
  
352
  /** Show dependency graph */
353
  graph?: boolean;
354
}
355
```
356

357
## Architecture
358

359
@lerna/list is implemented as a legacy wrapper package that provides backward compatibility while leveraging the shared Lerna command infrastructure:
360

361
1. **Wrapper Layer**: The published `@lerna/list` package re-exports functionality from the core Lerna command library
362
2. **Command Implementation**: The actual `ListCommand` class extends the base `Command` class from `@lerna/core`
363
3. **CLI Integration**: Uses yargs command modules for seamless integration with the Lerna CLI
364
4. **Core Dependencies**: Leverages shared utilities from `@lerna/core` for package filtering, formatting, and output
365

366
The command follows Lerna's standard command lifecycle:
367
1. **Initialization**: Filters packages based on options and formats output
368
2. **Execution**: Outputs the formatted results and logs success statistics
369

370
This architecture ensures consistency with other Lerna commands while providing the flexibility to use the package independently or as part of the broader Lerna toolchain.