0
# Task System
1

2
Buidler's task system is the core organizational principle that structures all development operations. Tasks are composable, extensible units of work that can be chained, overridden, and parameterized with type safety.
3

4
## Capabilities
5

6
### Task Definition
7

8
Create new tasks or internal tasks that can be executed via the Buidler CLI or programmatically.
9

10
```typescript { .api }
11
/**
12
 * Define a new public task that appears in help output
13
 * @param name - Unique task name
14
 * @param description - Optional description for help output
15
 * @param action - Optional task implementation function
16
 * @returns Configurable task definition for chaining parameter definitions
17
 */
18
function task<ArgsT extends TaskArguments>(
19
  name: string,
20
  description?: string,
21
  action?: ActionType<ArgsT>
22
): ConfigurableTaskDefinition;
23

24
/**
25
 * Define an internal task that doesn't appear in help output
26
 * @param name - Unique task name
27
 * @param description - Optional description
28
 * @param action - Optional task implementation function
29
 * @returns Configurable task definition for chaining parameter definitions
30
 */
31
function internalTask<ArgsT extends TaskArguments>(
32
  name: string,
33
  description?: string,
34
  action?: ActionType<ArgsT>
35
): ConfigurableTaskDefinition;
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import { task, types } from "@nomiclabs/buidler/config";
42

43
// Simple task
44
task("hello", "Prints hello world", async () => {
45
  console.log("Hello, World!");
46
});
47

48
// Task with parameters
49
task("deploy", "Deploy contracts")
50
  .addParam("network", "Target network", "localhost", types.string)
51
  .addFlag("verify", "Verify contracts on Etherscan")
52
  .setAction(async (taskArgs, hre) => {
53
    console.log(`Deploying to ${taskArgs.network}`);
54
    if (taskArgs.verify) {
55
      console.log("Will verify contracts");
56
    }
57
    // Deployment logic here
58
  });
59

60
// Internal subtask
61
internalTask("compile:solidity", "Compile Solidity contracts", async (taskArgs, hre) => {
62
  // Compilation logic
63
});
64
```
65

66
### Task Configuration
67

68
Configure task parameters, flags, and descriptions after definition.
69

70
```typescript { .api }
71
interface ConfigurableTaskDefinition {
72
  /** Set task description shown in help output */
73
  setDescription(description: string): this;
74
  /** Set task action implementation */
75
  setAction(action: ActionType<TaskArguments>): this;
76
  /** Add a required or optional parameter with type validation */
77
  addParam<T>(
78
    name: string,
79
    description?: string,
80
    defaultValue?: T,
81
    type?: ArgumentType<T>,
82
    isOptional?: boolean
83
  ): this;
84
  /** Add an optional parameter with default value */
85
  addOptionalParam<T>(
86
    name: string,
87
    description?: string,
88
    defaultValue?: T,
89
    type?: ArgumentType<T>
90
  ): this;
91
  /** Add a required positional parameter */
92
  addPositionalParam<T>(
93
    name: string,
94
    description?: string,
95
    defaultValue?: T,
96
    type?: ArgumentType<T>,
97
    isOptional?: boolean
98
  ): this;
99
  /** Add an optional positional parameter */
100
  addOptionalPositionalParam<T>(
101
    name: string,
102
    description?: string,
103
    defaultValue?: T,
104
    type?: ArgumentType<T>
105
  ): this;
106
  /** Add a variadic positional parameter (array) */
107
  addVariadicPositionalParam<T>(
108
    name: string,
109
    description?: string,
110
    defaultValue?: T[],
111
    type?: ArgumentType<T>,
112
    isOptional?: boolean
113
  ): this;
114
  /** Add an optional variadic positional parameter */
115
  addOptionalVariadicPositionalParam<T>(
116
    name: string,
117
    description?: string,
118
    defaultValue?: T[],
119
    type?: ArgumentType<T>
120
  ): this;
121
  /** Add a boolean flag parameter */
122
  addFlag(name: string, description?: string): this;
123
}
124
```
125

126
### Task Execution
127

128
Execute tasks programmatically from within other tasks or scripts.
129

130
```typescript { .api }
131
/**
132
 * Execute a task by name with optional arguments
133
 * @param name - Task name to execute
134
 * @param taskArguments - Arguments to pass to the task
135
 * @returns Promise resolving to task result
136
 */
137
type RunTaskFunction = (
138
  name: string,
139
  taskArguments?: TaskArguments
140
) => Promise<any>;
141

142
/**
143
 * Execute the parent task implementation when overriding a task
144
 * @param taskArguments - Arguments to pass to parent task
145
 * @returns Promise resolving to parent task result
146
 */
147
interface RunSuperFunction<ArgT extends TaskArguments> {
148
  (taskArguments?: ArgT): Promise<any>;
149
  isDefined: boolean;
150
}
151
```
152

153
**Usage Examples:**
154

155
```typescript
156
// Execute task from within another task
157
task("build", "Build and test project", async (taskArgs, hre) => {
158
  await hre.run("clean");
159
  await hre.run("compile");
160
  await hre.run("test");
161
});
162

163
// Override existing task with super call
164
task("compile", "Extended compile with custom logic", async (taskArgs, hre, runSuper) => {
165
  console.log("Pre-compilation setup");
166
  
167
  // Call original compile task
168
  const result = await runSuper(taskArgs);
169
  
170
  console.log("Post-compilation cleanup");
171
  return result;
172
});
173
```
174

175
### Task Definition Interface
176

177
Complete task definition including metadata and parameter definitions.
178

179
```typescript { .api }
180
interface TaskDefinition extends ConfigurableTaskDefinition {
181
  /** Task name (read-only) */
182
  readonly name: string;
183
  /** Task description for help output */
184
  readonly description?: string;
185
  /** Task implementation function */
186
  readonly action: ActionType<TaskArguments>;
187
  /** Whether task is internal (hidden from help) */
188
  readonly isInternal: boolean;
189
  /** Named parameter definitions */
190
  readonly paramDefinitions: ParamDefinitionsMap;
191
  /** Positional parameter definitions in order */
192
  readonly positionalParamDefinitions: Array<ParamDefinition<any>>;
193
}
194

195
interface ParamDefinition<T> {
196
  name: string;
197
  defaultValue?: T;
198
  type: ArgumentType<T>;
199
  description?: string;
200
  isOptional: boolean;
201
  isFlag: boolean;
202
  isVariadic: boolean;
203
}
204

205
interface ParamDefinitionsMap {
206
  [paramName: string]: ParamDefinition<any>;
207
}
208
```
209

210
### Task Action Types
211

212
Type definitions for task implementation functions.
213

214
```typescript { .api }
215
/**
216
 * Task implementation function signature
217
 * @param taskArgs - Parsed task arguments
218
 * @param env - Buidler runtime environment
219
 * @param runSuper - Function to call parent task implementation
220
 * @returns Promise resolving to task result
221
 */
222
type ActionType<ArgsT extends TaskArguments> = (
223
  taskArgs: ArgsT,
224
  env: BuidlerRuntimeEnvironment,
225
  runSuper: RunSuperFunction<ArgsT>
226
) => Promise<any>;
227

228
/** Task arguments object (can be any shape) */
229
type TaskArguments = any;
230

231
/** Map of all registered tasks */
232
interface TasksMap {
233
  [name: string]: TaskDefinition;
234
}
235
```
236

237
### Argument Types
238

239
Built-in argument type validators for task parameters.
240

241
```typescript { .api }
242
interface ArgumentType<T> {
243
  /** Type name for error messages */
244
  name: string;
245
  /** Parse string value to typed value */
246
  parse(argName: string, strValue: string): T;
247
}
248

249
/** Built-in argument types */
250
const types = {
251
  /** String argument type */
252
  string: ArgumentType<string>;
253
  /** Boolean argument type */
254
  boolean: ArgumentType<boolean>;
255
  /** Integer argument type */
256
  int: ArgumentType<number>;
257
  /** Float argument type */
258
  float: ArgumentType<number>;
259
  /** File path argument type with existence validation */
260
  inputFile: ArgumentType<string>;
261
  /** JSON argument type with parsing validation */
262
  json: ArgumentType<any>;
263
};
264
```
265

266
**Usage Examples:**
267

268
```typescript
269
import { task, types } from "@nomiclabs/buidler/config";
270

271
task("process-data", "Process data file")
272
  .addParam("input", "Input JSON file", undefined, types.inputFile)
273
  .addParam("count", "Number of items to process", 10, types.int)
274
  .addFlag("verbose", "Enable verbose output")
275
  .setAction(async (taskArgs, hre) => {
276
    const data = JSON.parse(fs.readFileSync(taskArgs.input, 'utf8'));
277
    const itemsToProcess = data.slice(0, taskArgs.count);
278
    
279
    if (taskArgs.verbose) {
280
      console.log(`Processing ${itemsToProcess.length} items`);
281
    }
282
    
283
    // Process data...
284
  });
285
```
286

287
### Runtime Environment Access
288

289
Access the full Buidler runtime environment from within tasks.
290

291
```typescript { .api }
292
interface BuidlerRuntimeEnvironment {
293
  /** Resolved configuration with all defaults */
294
  readonly config: ResolvedBuidlerConfig;
295
  /** Parsed command-line arguments */
296
  readonly buidlerArguments: BuidlerArguments;
297
  /** Map of all registered tasks */
298
  readonly tasks: TasksMap;
299
  /** Function to execute tasks programmatically */
300
  readonly run: RunTaskFunction;
301
  /** Current network configuration and provider */
302
  readonly network: Network;
303
  /** Ethereum provider (deprecated, use network.provider) */
304
  readonly ethereum: EthereumProvider;
305
}
306
```