Skip to content

Commit

Permalink
Merge pull request #361 from bsinno/feature/254_cli_tool_doc_improvem…
Browse files Browse the repository at this point in the history 
…ents

Cli Tool documentation improvements. Fixes #254
  • Loading branch information
@aedelmann
aedelmann authored Jul 26, 2016
2 parents dc14b5e + c4f2ae4 commit fc382ca
Show file tree
Hide file tree
Showing 3 changed files with 142 additions and 51 deletions.
193 changes: 142 additions & 51 deletions website/documentation/vorto-repository/cli-tool/cli-tool.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,42 +17,61 @@ title: Vorto CLI Tool

## Overview

Vorto Command Line Interface (CLI) tool is REST-Client that allows you, to access your specified repository with all Vorto related functionalities.
The Vorto Command Line Interface (CLI) tool is a REST-Client that allows you to access your specified repository with all Vorto related functionalities.

## Basic Structure

The CLI-Tool is based on a simple structure.

It consists of a Command Line Interface as well as a `.yaml` file, that stores all necessary configuration properties like _Username_, _Password_, _Proxy_ and _Repository_.
The CLI-Tool is based on a simple structure. It consists of a *Command Line Interface* as well as a `.yaml` file, that stores all necessary configuration properties like _Username_, _Password_, _Proxy_ and _Repository_.

## Installation

First of all, you have to download the CLI Tool from the <a href="{{ base }}/downloads/index.html">download</a> page and save it to any working directory.
Download the CLI Tool from the <a href="{{ base }}/downloads/index.html">Vorto Downloads</a> page and save it to any working directory.

A very convenient way to use the CLI Tool is, to add the path of the directory into the system's environment PATH variable. Once you did this, you can call the CLI-Tool from any directory.

For Windows, open **Control Panel -> Advanced System Settings -> Advanced -> Environment Variables**

![Environment Variable]({{base}}/img/documentation/cli_evnmt_variable.jpg)

Before you can use the CLI Tool as a REST Client, you need to initialize basic preferences. The preferences are stored in the file `.vortocli.yaml`, which is located in your home directory (in Windows, for example: `C:\Users\{$username}\`).
For Mac/Linux, from a terminal window execute

export path=%path%:~/Applications/<<vorto cli tool installed directory>>

Before you can use the CLI Tool as a REST Client, you need to initialize basic preferences. By default the preferences are stored in the file `.vortocli.yaml.file`, which is located in your home directory.

For Windows,

C:\Users\{$username}\.vortocli.yaml.file

For Mac,

/Users/{$username}/Documents/.vortocli.yaml.file

For Linux,

You have to setup vorto in one of the following ways:
/usr/{$username}/Documents/.vortocli.yaml.file

* Use the **vorto config** command.
You have to setup the CLI Tool in one of the following ways:

* Use the `vorto config` command.
To initialize vorto with additional values (or change them afterwards) like username, password, proxy or repository, use the command flags `-username`, `-password`, `-proxy` or `-repo`.
Example: `vorto config -username <username> -password <password> -repo http://vorto.eclipse.org`
* Edit the `.vortocli.yaml` file with a text editor.
![CLI Yaml file]({{base}}/img/documentation/yamlfile.jpg)

Congratulations! - Setup is done and you are now able to use the Vorto CLI Tool.

<table class="table table-bordered">
<tbody>
<tr>
<td><i class="fa fa-info-circle info-note"></i></td>
<td>Enable the proxy in the configuration file <code>.vortocli.yaml</code> (Line 4) if you are accessing internet via proxy server.</td>
</tr>
</tbody>
</table>

## CLI Commands

Now let's continue how you can really gain a benefit from the CLI Tool.

The Vorto CLI Tool provides a scope of seven different Vorto Commands to interact with your specified Repository.

Each of them is based on a similar structure and offers a unique functionality.
The Vorto CLI Tool provides a scope of different Vorto Commands to interact with your specified Repository.
Each of them offers a unique functionality and is based on the following syntax:

vorto [command] [-flag1 parameter1 -flag2 parameter2 ... ]

Expand All @@ -66,45 +85,117 @@ Each of them is based on a similar structure and offers a unique functionality.
</thead>
<tbody>
<tr>
<td>vorto config</td>
<td>With the vorto config command you do the basic CLI Tool setup.<br>Additional flag parameters:<br><ul><li>username - vorto username credentials</li><li>password - vorto password credentials</li><li>proxy- network proxy</li><li>repo - specify repository (Default: http://vorto.eclipse.org/repo)</li></ul></td>
<td><b>vorto config -username andreas -password test1234 -repo http://vorto.eclipse.org/repo</b></td>
</tr>
<tr>
<td>vorto help</td>
<td>To get more familiar with the CLI Tool commands, it's a good approach to call the <b>vorto help</b> command.<br><b>vorto help</b> lists you all other possible commands, including flag parameters and examples.</td>
<td><b>vorto help</b></td>
</tr>
<tr>
<td>vorto query</td>
<td>After everything is successfully setup, you are able to access the Repository.<br> Via <b>vorto query</b> you can query all models of your Repository.<br>The result of this command contains all models in the Repository.</td>
<td><b>vorto query "*"</b></td>
<td><code>vorto config</code></td>
<td>With the vorto config command you do the basic CLI Tool setup.<br>Additional flag parameters:<br>
<ul>
<li><code>username</code><br>
Vorto Repository username credentials</li>
<li><code>password</code><br>
Vorto Repository password credentials</li>
<li><code>proxy</code><br>
network proxy</li>
<li><code>repo</code><br>
Vorto repository URL (default: <code>http://vorto.eclipse.org</code>)</li>
</ul>
</td>
<td>
For (Windows/Mac/Linux),<br/>
<p><code>vorto config -username vortouser -password password -repo http://vorto.eclipse.org</code></p>
</td>
</tr>
<tr>
<td><code>vorto help</code></td>
<td>To get more familiar with the CLI Tool commands, it's a good approach to call the <code>vorto help</code> command.<br><code>vorto help</code> lists you all other possible commands, including flag parameters and examples.</td>
<td>For (Windows/Mac/Linux),<br/>
<p><code>vorto help</code></b>
</td>
</tr>
<tr>
<td><code>vorto query</code></td>
<td>After everything is successfully setup, you are able to access the Repository.<br> Via <code>vorto query</code> you can query models of your Repository.
</td>
<td>
For (Windows/Mac/Linux),<br/><br>
Query all models of your Repository:<br>
<code>vorto query "*"</code><br><br>
Query all models containing the string <code>"functionblocks"</code>:<br>
<code>vorto query "*functionblocks*"</code></td>
</tr>
<tr>
<td>vorto info</td>
<td>If you are now interested in a certain model and you want to get more information from this specific model, you can use vorto info to get it.<br> The result of this command is a detailed view of the requested model.</td>
<td><b>vorto info examples.informationmodels.sensors.TI_SensorTag_CC2650:1.0.0</b></td>
<td><code>vorto info</code></td>
<td>If you are now interested in a certain model and you want to get more information from this specific model, you can use <code>vorto info</code> to get it.<br>
The result of this command is a detailed view of the requested model.</td>
<td>
For (Windows/Mac/Linux),<br/>
<code>vorto info examples.informationmodels.TI_SensorTag:1.0.0</code></td>
</tr>
<tr>
<td>vorto download</td>
<td>Furthermore you can start working with a certain model locally, when you download it via <b>vorto download</b>.<br> To open and to work with it, you can use any text editor to modify this certain model and you can even upload it again.<br>Via the flag -outputPath can you specify a download directory.<br>Additional flag parameters:<br><ul><li>output - (Default: DSL)</li><li>outputPath - path to store the download (Default: current directory)</li><li>includeDependencies - whether to include dependencies or not (Default: false)</li></ul></td>
<td><b>vorto download examples.informationmodels.sensors.TI_SensorTag_CC2650:1.0.0 -outputPath D:\models</b></td>
</tr>
<tr>
<td>vorto generators</td>
<td>If you want to generate platform specific code, you can get a short overview of all active code generators via <b>vorto generators</b>.</td>
<td><b>vorto generators</b></td>
</tr>
<tr>
<td>vorto generate</td>
<td>Afterwards you can generate <b>vorto generate</b> your platform specific code (specified by -generatorKey) in a very convenient way.<br>Additional flag parameters:<br><ul><li>generatorKey</li><li>outputPath</li></ul></td>
<td><b>vorto generators</b></td>
</tr>
<tr>
<td>vorto share</td>
<td>Additionally to all this access functionality, you are also able to share your models.<br>Therefore you either have to deposit your credentials in the .vortocli.yaml file or you have to pass them as additional parameters.<br>
Additional flag parameters:<br><ul><li>username - vorto username credentials (Default: value in .vortocli.yaml)</li><li>password - vorto password credentials (Default: value in .vortocli.yaml)</li></ul></td>
<td><b>vorto share D:\Models\ TI_SensorTag_CC2650\src\models\ TI_SensorTag_CC2650.infomodel</b><br><b>vorto share D:\Models\ TI_SensorTag_CC2650\src\models\ TI_SensorTag_CC2650.infomodel -username andreas -password test1234</b></td>
</tr>
<td><code>vorto download</code></td>
<td>Furthermore you can start working with a certain model locally, when you download it via <code>vorto download</code>.<br>
To open and to work with it, you can use any text editor to modify this certain model and you can even upload it again.<br>
Via the flag <code>-outputPath</code> you can specify a download directory.<br>
Additional flag parameters:<br>
<ul>
<li><code>output</code><br>
output format (default: <code>DSL</code>)</li>
<li><code>outputPath</code><br>
path to store the download (default: current directory)</li>
<li><code>includeDependencies</code><br>
whether to include dependencies or not (default: <code>false</code>)</li>
</ul>
</td>
<td>
For Windows,<br/>
<code>vorto download examples.informationmodels.TI_SensorTag:1.0.0 -outputPath D:\models</code><br/><br/>
For Mac/Linux,<br/>
<code>vorto download examples.informationmodels.TI_SensorTag:1.0.0 -outputPath /Users/{$username}/Documents/models/</code>
</td>
</tr>
<tr>
<td><code>vorto generators</code></td>
<td>If you want to generate platform specific code, you can get a short overview of all active code generators via <code>vorto generators</code>.
</td>
<td>
For (Windows/Mac/Linux),<br/>
<code>vorto generators</code>
</td>
</tr>
<tr>
<td><code>vorto generate</code></td>
<td>Afterwards you can generate <code>vorto generate</code> your platform specific code (specified by <code>-generatorKey</code>) in a very convenient way.<br>
Additional flag parameters:<br>
<ul>
<li><code>generatorKey</code></li>
<li><code>outputPath</code></li>
</ul>
</td>
<td>
For Windows, <br/>
<code>vorto generate examples.informationmodels.TI_SensorTag:1.0.0 -generatorKey mqtt -outputPath D:\models</code><br/><br/>
For Mac/Linux,<br/>
<code>vorto generate examples.informationmodels.TI_SensorTag:1.0.0 -generatorKey mqtt -outputPath /Users/{$username}/Documents/models</code>
</td>
</tr>
<tr>
<td><code>vorto share<code></td>
<td>Additionally to all this access functionality, you are also able to share your models.<br>
Therefore you either have to deposit your credentials in the <code>.vortocli.yaml</code> file or you have to pass them as additional parameters.<br>
Additional flag parameters:<br>
<ul>
<li><code>username</code><br>
Vorto Repository username credentials (default: value in <code>.vortocli.yaml</code>)</li>
<li><code>password</code><br>
Vorto Repository password credentials (default: value in <code>.vortocli.yaml</code>)</li>
</ul>
</td>
<td>
For Windows,<br/>
<code>vorto share D:\Models\TI_SensorTag_CC2650\src\models\TI_SensorTag.infomodel</code><br/>
<code>vorto share D:\Models\TI_SensorTag_CC2650\src\models\TI_SensorTag.infomodel -username vortouser -password password</code><br/><br/>
For Mac/Linux,<br/>
<code>vorto share /Users/{$username}/Documents/models/TI_SensorTag.infomodel</code><br/><br/>
<code>vorto share /Users/{$username}/Documents/models/TI_SensorTag.infomodel -username vortouser -password password</code>
</td>
</tr>
</tbody>
</table>
Binary file modified website/img/documentation/cli_evnmt_variable.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified website/img/documentation/yamlfile.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit fc382ca

Please sign in to comment.