0
# Commands
1

2
The command system provides a unified interface for executing build operations with standardized error handling and promise-based execution.
3

4
## Capabilities
5

6
### Command Interface
7

8
Common interface for all commands with generic type support.
9

10
```typescript { .api }
11
/**
12
 * Common call signature for a command
13
 */
14
interface Command<Arguments, Result> {
15
  (args?: Arguments): Result | Promise<Result>;
16
}
17
```
18

19
### Execute Function
20

21
Executes any command and ensures the result is properly promisified.
22

23
```typescript { .api }
24
/**
25
 * Executes a Command and returns its promisified result
26
 * @param command - The command to execute
27
 * @param args - Arguments to pass to the command
28
 * @returns Promise resolving to command result
29
 */
30
function execute<A, R>(command: Command<A, R>, args?: A): Promise<R>;
31
```
32

33
**Usage Example:**
34

35
```typescript
36
import { execute, build } from "ng-packagr";
37

38
const args = {
39
  project: './ng-package.json',
40
  watch: false
41
};
42

43
await execute(build, args);
44
```
45

46
### Build Command
47

48
Command for performing one-off builds of Angular libraries.
49

50
```typescript { .api }
51
/**
52
 * Command running an "one-off" build
53
 */
54
const build: Command<CliArguments, void>;
55
```
56

57
**Usage Examples:**
58

59
```typescript
60
import { build } from "ng-packagr";
61

62
// Direct command usage
63
await build({
64
  project: './ng-package.json',
65
  watch: false
66
});
67

68
// With custom TypeScript config
69
await build({
70
  project: './ng-package.json',
71
  config: './tsconfig.lib.json'
72
});
73

74
// With watch mode
75
await build({
76
  project: './ng-package.json',
77
  watch: true,
78
  poll: 1000
79
});
80
```
81

82
### Version Command
83

84
Command for printing version information for ng-packagr and its dependencies.
85

86
```typescript { .api }
87
/**
88
 * Prints version information
89
 */
90
const version: Command<any, Promise<void>>;
91
```
92

93
**Usage Example:**
94

95
```typescript
96
import { version } from "ng-packagr";
97

98
// Print version information
99
await version();
100
// Outputs:
101
// ng-packagr:            20.2.0
102
// @angular/compiler:     20.2.0
103
// typescript:            5.9.2
104
```
105

106
## CLI Arguments Interface
107

108
Defines the structure of arguments passed to CLI commands.
109

110
```typescript { .api }
111
/**
112
 * CLI arguments passed to `ng-packagr` executable and `build()` command
113
 */
114
interface CliArguments {
115
  /** Path to the project file 'package.json', 'ng-package.json', or 'ng-package.js' */
116
  project: string;
117
  /** Whether or not ng-packagr will watch for file changes and perform an incremental build */
118
  watch?: boolean;
119
  /** Path to a tsconfig file */
120
  config?: string;
121
  /** Enable and define the file watching poll time period in milliseconds */
122
  poll?: number;
123
}
124
```
125

126
## Command Execution Patterns
127

128
### Error Handling
129

130
Commands automatically handle both synchronous and asynchronous errors:
131

132
```typescript
133
import { execute, build } from "ng-packagr";
134

135
try {
136
  await execute(build, { project: './ng-package.json' });
137
  console.log('Build completed successfully');
138
} catch (error) {
139
  console.error('Build failed:', error.message);
140
}
141
```
142

143
### Custom Commands
144

145
You can create custom commands that follow the Command interface:
146

147
```typescript
148
import { Command, execute } from "ng-packagr";
149

150
const customBuild: Command<{ projectPath: string }, void> = async (args) => {
151
  console.log(`Building project at ${args.projectPath}`);
152
  // Custom build logic here
153
};
154

155
// Execute custom command
156
await execute(customBuild, { projectPath: './my-project' });
157
```