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


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

QuanluZhang's avatar
QuanluZhang committed
6
7
8
__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
9

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

```bash
QuanluZhang's avatar
QuanluZhang committed
13
14
15
16
17
18
19
20
nnictl create
nnictl stop
nnictl update
nnictl resume
nnictl trial
nnictl experiment
nnictl config
nnictl log
SparkSnail's avatar
SparkSnail committed
21
nnictl webui
chicm-ms's avatar
chicm-ms committed
22
nnictl tensorboard
SparkSnail's avatar
SparkSnail committed
23
nnictl top
SparkSnail's avatar
SparkSnail committed
24
nnictl --version
QuanluZhang's avatar
QuanluZhang committed
25
```
Chi Song's avatar
Chi Song committed
26

QuanluZhang's avatar
QuanluZhang committed
27
### Manage an experiment
Chi Song's avatar
Chi Song committed
28
29
30
31
32
33
34

* __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
35
  * Usage
Chi Song's avatar
Chi Song committed
36
37
38
39
40
41
42
43
44
45

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

    Options:  
    | Name, shorthand | Required|Default | Description |
    | ------ | ------ | ------ |------ |
    | --config, -c|  True| |yaml configure file of the experiment|
    | --port, -p  |  False| |the port of restful server|
QuanluZhang's avatar
QuanluZhang committed
46
47
48
49

* __nnictl resume__

  * Description
Chi Song's avatar
Chi Song committed
50
51
52

    You can use this command to resume a stopped experiment.

QuanluZhang's avatar
QuanluZhang committed
53
  * Usage
Chi Song's avatar
Chi Song committed
54
55
56
57
58
59
60
61
62

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

    Options:

    | Name, shorthand | Required|Default | Description |
    | ------ | ------ | ------ |------ |
63
64
    | id|  False| |The id of the experiment you want to resume|  
    | --port, -p|  False| |Rest port of the experiment you want to resume|
QuanluZhang's avatar
QuanluZhang committed
65
66
67

* __nnictl stop__
  * Description
Chi Song's avatar
Chi Song committed
68
69
70

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

QuanluZhang's avatar
QuanluZhang committed
71
  * Usage
Chi Song's avatar
Chi Song committed
72
73
74
75

    ```bash
    nnictl stop [id]
    ```
SparkSnail's avatar
SparkSnail committed
76
77
  
  * Detail
Chi Song's avatar
Chi Song committed
78
79
80
81
82
83
84
85
86
87
88
89
90

    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  

QuanluZhang's avatar
QuanluZhang committed
91
* __nnictl update__
Chi Song's avatar
Chi Song committed
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

  * __nnictl update searchspace__
    * Description

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

    * Usage

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

      Options:

      | 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|

  * __nnictl update concurrency__  
    * Description

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

    * Usage

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

      Options:

      | Name, shorthand | Required|Default | Description |
      | ------ | ------ | ------ |------ |
      | id|  False| |ID of the experiment you want to set|
      | --value, -v|  True| |the number of allowed concurrent trials|

  * __nnictl update duration__  
    * Description

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

    * Usage

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

      Options:

      | 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.|  

  * __nnictl update trialnum__  
    * Description

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

    * Usage

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

      | 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|
QuanluZhang's avatar
QuanluZhang committed
163
164

* __nnictl trial__
Chi Song's avatar
Chi Song committed
165

QuanluZhang's avatar
QuanluZhang committed
166
  * __nnictl trial ls__
Chi Song's avatar
Chi Song committed
167

QuanluZhang's avatar
QuanluZhang committed
168
    * Description
Chi Song's avatar
Chi Song committed
169
170
171
172

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

    * Usage
QuanluZhang's avatar
QuanluZhang committed
173
  
Chi Song's avatar
Chi Song committed
174
175
176
      ```bash
      nnictl trial ls
      ```
QuanluZhang's avatar
QuanluZhang committed
177

SparkSnail's avatar
SparkSnail committed
178
      Options:
Chi Song's avatar
Chi Song committed
179

SparkSnail's avatar
SparkSnail committed
180
181
      | Name, shorthand | Required|Default | Description |
      | ------ | ------ | ------ |------ |
Chi Song's avatar
Chi Song committed
182
      | id|  False| |ID of the experiment you want to set|
SparkSnail's avatar
SparkSnail committed
183

QuanluZhang's avatar
QuanluZhang committed
184
  * __nnictl trial kill__
Chi Song's avatar
Chi Song committed
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
    * Description

      You can use this command to kill a trial job.

    * Usage

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

      | Name, shorthand | Required|Default | Description |
      | ------ | ------ | ------ |------ |
      | id|  False| |ID of the experiment you want to set|
      | --trialid, -t|  True| |ID of the trial you want to kill.|
SparkSnail's avatar
SparkSnail committed
200
201
202
  
  * __nnictl top__

Chi Song's avatar
Chi Song committed
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
    * Description

      Monitor all of running experiments.

    * Usage

      ```bash  
      nnictl top
      ```  

      Options:  

      | 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.|
QuanluZhang's avatar
QuanluZhang committed
219
220
221
222

### Manage experiment information

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

QuanluZhang's avatar
QuanluZhang committed
224
  * Description
SparkSnail's avatar
SparkSnail committed
225

Chi Song's avatar
Chi Song committed
226
227
228
229
230
231
232
233
234
235
236
237
238
    Show the information of experiment.

  * Usage

    ```bash
    nnictl experiment show
    ```

    Options:

    | Name, shorthand | Required|Default | Description |
    | ------ | ------ | ------ |------ |
    | id|  False| |ID of the experiment you want to set|
SparkSnail's avatar
SparkSnail committed
239
240

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

SparkSnail's avatar
SparkSnail committed
242
243
  * Description

Chi Song's avatar
Chi Song committed
244
245
246
247
248
249
250
251
252
253
254
255
256
    Show the status of experiment.

  * Usage

    ```bash
    nnictl experiment status
    ```

    Options:

    | Name, shorthand | Required|Default | Description |
    | ------ | ------ | ------ |------ |
    | id|  False| |ID of the experiment you want to set|
SparkSnail's avatar
SparkSnail committed
257
258
259

* __nnictl experiment list__
  * Description
QuanluZhang's avatar
QuanluZhang committed
260

Chi Song's avatar
Chi Song committed
261
262
263
    Show the information of all the (running) experiments.

  * Usage
264

Chi Song's avatar
Chi Song committed
265
266
267
268
269
270
271
272
273
    ```bash
    nnictl experiment list
    ```

    Options:

    | Name, shorthand | Required|Default | Description |
    | ------ | ------ | ------ |------ |
    | all|  False| False|Show all of experiments, including stopped experiments.|
QuanluZhang's avatar
QuanluZhang committed
274
275

* __nnictl config show__
Chi Song's avatar
Chi Song committed
276
277
278
279
280
281
282
283
284
285
  * Description

    Display the current context information.

  * Usage

    ```bash
    nnictl config show
    ```

QuanluZhang's avatar
QuanluZhang committed
286
### Manage log
Chi Song's avatar
Chi Song committed
287

QuanluZhang's avatar
QuanluZhang committed
288
* __nnictl log stdout__
Chi Song's avatar
Chi Song committed
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308

  * Description

    Show the stdout log content.

  * Usage

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

    Options:

    | 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|

QuanluZhang's avatar
QuanluZhang committed
309
310
* __nnictl log stderr__
  * Description
Chi Song's avatar
Chi Song committed
311
312

    Show the stderr log content.
QuanluZhang's avatar
QuanluZhang committed
313
314
  
  * Usage
Chi Song's avatar
Chi Song committed
315
316
317
318
319
320
321
322
323

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

    Options:

    | Name, shorthand | Required|Default | Description |
    | ------ | ------ | ------ |------ |
324
    | id|  False| |ID of the experiment you want to set|
QuanluZhang's avatar
QuanluZhang committed
325
326
    | --head, -h| False| |show head lines of stderr|
    | --tail, -t|  False| |show tail lines of stderr|
Chi Song's avatar
Chi Song committed
327
    | --path, -p|  False| |show the path of stderr file|
328
329
330
331

* __nnictl log trial__
  * Description
  
Chi Song's avatar
Chi Song committed
332
    Show trial log path.
333
334
  
  * Usage
SparkSnail's avatar
SparkSnail committed
335

Chi Song's avatar
Chi Song committed
336
337
338
339
340
341
342
343
344
    ```bash  
    nnictl log trial [options]
    ```

    Options:

    | Name, shorthand | Required|Default | Description |
    | ------ | ------ | ------ |------ |
    | id| False| |the id of trial|
SparkSnail's avatar
SparkSnail committed
345
346

### Manage webui
Chi Song's avatar
Chi Song committed
347

SparkSnail's avatar
SparkSnail committed
348
* __nnictl webui url__
SparkSnail's avatar
SparkSnail committed
349

Chi Song's avatar
Chi Song committed
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
  * Description

    Show the urls of the experiment.

  * Usage

    ```bash
    nnictl webui url
    ```

    Options:

    | Name, shorthand | Required|Default | Description |
    | ------ | ------ | ------ |------ |
    | id|  False| |ID of the experiment you want to set|
SparkSnail's avatar
SparkSnail committed
365
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
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394

  * Description

    Start the tensorboard process.
  
  * Usage

    ```bash
    nnictl tensorboard start
    ```

    Options:

    | 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|

  * 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__
Chi Song's avatar
Chi Song committed
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
  * Description

    Stop all of the tensorboard process.

  * Usage

    ```bash
    nnictl tensorboard stop
    ```

    Options:

    | Name, shorthand | Required|Default | Description |
    | ------ | ------ | ------ |------ |
    | id|  False| |ID of the experiment you want to set|
SparkSnail's avatar
SparkSnail committed
412
413
414
415

### Check nni version

* __nnictl --version__
Chi Song's avatar
Chi Song committed
416

SparkSnail's avatar
SparkSnail committed
417
  * Description
Chi Song's avatar
Chi Song committed
418

SparkSnail's avatar
SparkSnail committed
419
420
421
    Describe the current version of nni installed.
  
  * Usage
Chi Song's avatar
Chi Song committed
422
423
424
425

    ```bash
    nnictl --version
    ```