NNICTLDOC.md 10.2 KB
Newer Older
QuanluZhang's avatar
QuanluZhang committed
1
# nnictl
Chi Song's avatar
Chi Song committed
2

QuanluZhang's avatar
QuanluZhang committed
3
## Introduction
Chi Song's avatar
Chi Song committed
4

QuanluZhang's avatar
QuanluZhang committed
5
6
7
__nnictl__ is a command line tool, which can be used to control experiments, such as start/stop/resume an experiment, start/stop NNIBoard, etc.

## Commands
Chi Song's avatar
Chi Song committed
8

QuanluZhang's avatar
QuanluZhang committed
9
nnictl support commands:
Chi Song's avatar
Chi Song committed
10

11
12
13
14
15
16
17
18
19
20
21
22
23
* [nnictl create](#create)
* [nnictl resume](#resume)
* [nnictl stop](#stop)
* [nnictl update](#update)
* [nnictl trial](#trial)
* [nnictl top](#top)
* [nnictl experiment](#experiment)
* [nnictl config](#config)
* [nnictl log](#log)
* [nnictl webui](#webui)
* [nnictl tensorboard](#tensorboard)
* [nnictl package](#package)
* [nnictl --version](#version)
Chi Song's avatar
Chi Song committed
24

Yan Ni's avatar
Yan Ni committed
25
### Manage an experiment
26

Yan Ni's avatar
Yan Ni committed
27
<a name="create"></a>
28
29
30
31
32
33
34
35
* __nnictl create__

  * Description

    You can use this command to create a new experiment, using the configuration specified in config file. 

    After this command is successfully done, the context will be set as this experiment, which means the following command you issued is associated with this experiment, unless you explicitly changes the context(not supported yet).

QuanluZhang's avatar
QuanluZhang committed
36
  * Usage
37
38
39
40
41
42
43

    ```bash
    nnictl create [OPTIONS]
    ```

  * Options

Chi Song's avatar
Chi Song committed
44
45
46
47
  |Name, shorthand|Required|Default|Description|
  |------|------|------|------|
  |--config, -c|  True| |YAML configure file of the experiment|
  |--port, -p|False| |the port of restful server|
48
49
50
51
52
53
  |--debug, -d|False||set debug mode|

  Note:
  ```
  Debug mode will disable version check function in Trialkeeper.
  ```
54

Yan Ni's avatar
Yan Ni committed
55
<a name="resume"></a>
QuanluZhang's avatar
QuanluZhang committed
56
57
58
* __nnictl resume__

  * Description
Chi Song's avatar
Chi Song committed
59
60
61

    You can use this command to resume a stopped experiment.

QuanluZhang's avatar
QuanluZhang committed
62
  * Usage
Chi Song's avatar
Chi Song committed
63
64
65
66
67

    ```bash
    nnictl resume [OPTIONS]
    ```

68
69
  * Options

Chi Song's avatar
Chi Song committed
70
71
72
73
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |The id of the experiment you want to resume|  
  |--port, -p|  False| |Rest port of the experiment you want to resume|
74
  |--debug, -d|False||set debug mode|
Chi Song's avatar
Chi Song committed
75

Yan Ni's avatar
Yan Ni committed
76
<a name="stop"></a>
QuanluZhang's avatar
QuanluZhang committed
77
* __nnictl stop__
78

QuanluZhang's avatar
QuanluZhang committed
79
  * Description
Chi Song's avatar
Chi Song committed
80
81
82

    You can use this command to stop a running experiment or multiple experiments.

QuanluZhang's avatar
QuanluZhang committed
83
  * Usage
Chi Song's avatar
Chi Song committed
84
85
86
87

    ```bash
    nnictl stop [id]
    ```
SparkSnail's avatar
SparkSnail committed
88
89
  
  * Detail
90

Chi Song's avatar
Chi Song committed
91
92
93
94
95
96
    1. If there is an id specified, and the id matches the running experiment, nnictl will stop the corresponding experiment, or will print error message.
    2. If there is no id specified, and there is an experiment running, stop the running experiment, or print error message.
    3. If the id ends with *, nnictl will stop all experiments whose ids matchs the regular.
    4. If the id does not exist but match the prefix of an experiment id, nnictl will stop the matched experiment.
    5. If the id does not exist but match multiple prefix of the experiment ids, nnictl will give id information.
    6. Users could use 'nnictl stop all' to stop all experiments.
97

Yan Ni's avatar
Yan Ni committed
98
<a name="update"></a>
QuanluZhang's avatar
QuanluZhang committed
99
* __nnictl update__
100
101
102
103
104
105
106
107
108
109
110
111
112
113

  * __nnictl update searchspace__
    * Description

      You can use this command to update an experiment's search space.

    * Usage

      ```bash
      nnictl update searchspace [OPTIONS]
      ```

    * Options

Chi Song's avatar
Chi Song committed
114
115
116
117
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |ID of the experiment you want to set|
  |--filename, -f|  True| |the file storing your new search space|
118
119
120
121
122
123
124
125
126
127
128
129
130
131

  * __nnictl update concurrency__  
    * Description

      You can use this command to update an experiment's concurrency.

    * Usage

      ```bash
      nnictl update concurrency [OPTIONS]
      ```

    * Options

Chi Song's avatar
Chi Song committed
132
133
134
135
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |ID of the experiment you want to set|
  |--value, -v|  True| |the number of allowed concurrent trials|
136
137
138
139
140

  * __nnictl update duration__  

    * Description

141
      You can use this command to update an experiment's duration.  
142
143
144
145
146
147
148
149

    * Usage

      ```bash
      nnictl update duration [OPTIONS]
      ```
    * Options

Chi Song's avatar
Chi Song committed
150
151
152
153
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |ID of the experiment you want to set|
  |--value, -v|  True| |the experiment duration will be NUMBER seconds. SUFFIX may be 's' for seconds (the default), 'm' for minutes, 'h' for hours or 'd' for days.|
154
155
156
157
158
159
160
161
162
163
164
165
166
167

  * __nnictl update trialnum__  
    * Description

      You can use this command to update an experiment's maxtrialnum.

    * Usage

      ```bash
      nnictl update trialnum [OPTIONS]
      ```

    * Options

Chi Song's avatar
Chi Song committed
168
169
170
171
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |ID of the experiment you want to set|
  |--value, -v|  True| |the new number of maxtrialnum you want to set|
172

Yan Ni's avatar
Yan Ni committed
173
<a name="trial"></a>
QuanluZhang's avatar
QuanluZhang committed
174
* __nnictl trial__
Chi Song's avatar
Chi Song committed
175

QuanluZhang's avatar
QuanluZhang committed
176
  * __nnictl trial ls__
Chi Song's avatar
Chi Song committed
177

QuanluZhang's avatar
QuanluZhang committed
178
    * Description
Chi Song's avatar
Chi Song committed
179
180
181
182

      You can use this command to show trial's information.

    * Usage
183

Chi Song's avatar
Chi Song committed
184
185
186
      ```bash
      nnictl trial ls
      ```
QuanluZhang's avatar
QuanluZhang committed
187

188
    * Options
Chi Song's avatar
Chi Song committed
189

Chi Song's avatar
Chi Song committed
190
191
192
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |ID of the experiment you want to set|
SparkSnail's avatar
SparkSnail committed
193

QuanluZhang's avatar
QuanluZhang committed
194
  * __nnictl trial kill__
195
196
197
198
199
200
201
202
203
204
205
206
207

    * Description

      You can use this command to kill a trial job.

    * Usage

      ```bash
      nnictl trial kill [OPTIONS]
      ```

    * Options  

Chi Song's avatar
Chi Song committed
208
209
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
210
211
  |id|  False| |ID of the trial to be killed|
  |--experiment, -E|  True| |Experiment id of the trial|
212

Yan Ni's avatar
Yan Ni committed
213
214
<a name="top"></a>
* __nnictl top__
SparkSnail's avatar
SparkSnail committed
215

216
217
218
219
220
221
222
223
224
225
226
227
  * Description

    Monitor all of running experiments.

  * Usage

    ```bash
    nnictl top
    ```

  * Options  

Chi Song's avatar
Chi Song committed
228
229
230
231
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |ID of the experiment you want to set|
  |--time, -t|  False| |The interval to update the experiment status, the unit of time is second, and the default value is 3 second.|
232

Yan Ni's avatar
Yan Ni committed
233
<a name="experiment"></a>
QuanluZhang's avatar
QuanluZhang committed
234
235
236
### Manage experiment information

* __nnictl experiment show__
Chi Song's avatar
Chi Song committed
237

QuanluZhang's avatar
QuanluZhang committed
238
  * Description
SparkSnail's avatar
SparkSnail committed
239

Chi Song's avatar
Chi Song committed
240
241
242
243
244
245
246
247
    Show the information of experiment.

  * Usage

    ```bash
    nnictl experiment show
    ```

248
  * Options
Chi Song's avatar
Chi Song committed
249

Chi Song's avatar
Chi Song committed
250
251
252
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |ID of the experiment you want to set|
SparkSnail's avatar
SparkSnail committed
253
254

* __nnictl experiment status__
Chi Song's avatar
Chi Song committed
255

SparkSnail's avatar
SparkSnail committed
256
257
  * Description

Chi Song's avatar
Chi Song committed
258
259
260
261
262
263
264
265
    Show the status of experiment.

  * Usage

    ```bash
    nnictl experiment status
    ```

266
  * Options
Chi Song's avatar
Chi Song committed
267

Chi Song's avatar
Chi Song committed
268
269
270
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |ID of the experiment you want to set|
SparkSnail's avatar
SparkSnail committed
271
272

* __nnictl experiment list__
273

SparkSnail's avatar
SparkSnail committed
274
  * Description
QuanluZhang's avatar
QuanluZhang committed
275

Chi Song's avatar
Chi Song committed
276
277
278
    Show the information of all the (running) experiments.

  * Usage
279

Chi Song's avatar
Chi Song committed
280
281
282
283
    ```bash
    nnictl experiment list
    ```

Yan Ni's avatar
Yan Ni committed
284
<a name="config"></a>
QuanluZhang's avatar
QuanluZhang committed
285
* __nnictl config show__
286
287
288
289
290
291
292
293
294
295
296

  * Description

    Display the current context information.

  * Usage

    ```bash
    nnictl config show
    ```

Yan Ni's avatar
Yan Ni committed
297
<a name="log"></a>
QuanluZhang's avatar
QuanluZhang committed
298
### Manage log
Chi Song's avatar
Chi Song committed
299

QuanluZhang's avatar
QuanluZhang committed
300
* __nnictl log stdout__
Chi Song's avatar
Chi Song committed
301
302
303
304
305
306
307
308
309
310
311

  * Description

    Show the stdout log content.

  * Usage

    ```bash
    nnictl log stdout [options]
    ```

312
  * Options
Chi Song's avatar
Chi Song committed
313

Chi Song's avatar
Chi Song committed
314
315
316
317
318
319
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |ID of the experiment you want to set|
  |--head, -h| False| |show head lines of stdout|
  |--tail, -t|  False| |show tail lines of stdout|
  |--path, -p|  False| |show the path of stdout file|
Chi Song's avatar
Chi Song committed
320

QuanluZhang's avatar
QuanluZhang committed
321
322
* __nnictl log stderr__
  * Description
Chi Song's avatar
Chi Song committed
323
324

    Show the stderr log content.
325

QuanluZhang's avatar
QuanluZhang committed
326
  * Usage
Chi Song's avatar
Chi Song committed
327
328
329
330
331

    ```bash
    nnictl log stderr [options]
    ```

332
  * Options
Chi Song's avatar
Chi Song committed
333

Chi Song's avatar
Chi Song committed
334
335
336
337
338
339
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |ID of the experiment you want to set|
  |--head, -h| False| |show head lines of stderr|
  |--tail, -t|  False| |show tail lines of stderr|
  |--path, -p|  False| |show the path of stderr file|
340
341

* __nnictl log trial__
342

343
344
  * Description
  
Chi Song's avatar
Chi Song committed
345
    Show trial log path.
346
347
  
  * Usage
SparkSnail's avatar
SparkSnail committed
348

349
350
351
352
353
354
    ```bash  
    nnictl log trial [options]
    ```

  * Options

Chi Song's avatar
Chi Song committed
355
356
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
357
358
  |id|  False| |ID of the trial to be found the log path|
  |--experiment, -E|  False| |Experiment ID of the trial, required when id is not empty.|
359

Yan Ni's avatar
Yan Ni committed
360
<a name="webui"></a>
SparkSnail's avatar
SparkSnail committed
361
### Manage webui
Chi Song's avatar
Chi Song committed
362

SparkSnail's avatar
SparkSnail committed
363
* __nnictl webui url__
SparkSnail's avatar
SparkSnail committed
364

Yan Ni's avatar
Yan Ni committed
365
<a name="tensorboard"></a>
SparkSnail's avatar
SparkSnail committed
366
### Manage tensorboard
Chi Song's avatar
Chi Song committed
367

SparkSnail's avatar
SparkSnail committed
368
* __nnictl tensorboard start__
Chi Song's avatar
Chi Song committed
369
370
371
372
373
374
375
376
377
378
379

  * Description

    Start the tensorboard process.
  
  * Usage

    ```bash
    nnictl tensorboard start
    ```

380
  * Options
Chi Song's avatar
Chi Song committed
381

Chi Song's avatar
Chi Song committed
382
383
384
385
386
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |ID of the experiment you want to set|
  |--trialid|  False| |ID of the trial|
  |--port|  False| 6006|The port of the tensorboard process|
Chi Song's avatar
Chi Song committed
387
388
389
390
391
392
393
394

  * Detail

    1. NNICTL support tensorboard function in local and remote platform for the moment, other platforms will be supported later.   
    2. If you want to use tensorboard, you need to write your tensorboard log data to environment variable [NNI_OUTPUT_DIR] path.  
    3. In local mode, nnictl will set --logdir=[NNI_OUTPUT_DIR] directly and start a tensorboard process.
    4. In remote mode, nnictl will create a ssh client to copy log data from remote machine to local temp directory firstly, and then start a tensorboard process in your local machine. You need to notice that nnictl only copy the log data one time when you use the command, if you want to see the later result of tensorboard, you should execute nnictl tensorboard command again.
    5. If there is only one trial job, you don't need to set trialid. If there are multiple trial jobs running, you should set the trialid, or you could use [nnictl tensorboard start --trialid all] to map --logdir to all trial log paths.
SparkSnail's avatar
SparkSnail committed
395
396

* __nnictl tensorboard stop__
397
398
399
400
401
402
403
404
405
406
407
408
  * Description

    Stop all of the tensorboard process. 

  * Usage

    ```bash
    nnictl tensorboard stop
    ```

  * Options

Chi Song's avatar
Chi Song committed
409
410
411
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |id|  False| |ID of the experiment you want to set|
Yan Ni's avatar
Yan Ni committed
412
413
414

<a name="package"></a>
### Manage package
415

Yan Ni's avatar
Yan Ni committed
416
* __nnictl package install__
417
418
419
420
421
422
423
424
425
426
427
428
  * Description

    Install the packages needed in nni experiments.

  * Usage

    ```bash
    nnictl package install [OPTIONS]
    ```

  * Options

Chi Song's avatar
Chi Song committed
429
430
431
  |Name, shorthand|Required|Default|Description|
  |------|------|------ |------|
  |--name|  True| |The name of package to be installed|
Yan Ni's avatar
Yan Ni committed
432
433

* __nnictl package show__
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458

  * Description

    List the packages supported.

  * Usage

    ```bash
    nnictl package show
    ```

<a name="version"></a>
### Check NNI version

* __nnictl --version__

  * Description

    Describe the current version of NNI installed.

  * Usage

    ```bash
    nnictl --version
    ```