Use the `help` command to obtain help on the CLI's available commands:

```shell
solui help
```

This will output something like:

```
solui

  Develop and publish Dapps for smart contracts. For more information
  see https://solui.dev.

Usage

  $ solui <command> [options]

Commands

  login     Login to the solUI cloud and obtain an authentication token.
  publish   Publish a Dapo to the solUI cloud.
  version   Display solUI version.
  view      Render a Dapp and interact with it in your browser.
  help      Print this usage guide. Use "help <command>" for help on a specific command.
```

To get help on an individual command use:

```shell
solui help <command name>
```


Command: help

![Dapp mockup](../../images/RootLayout.png)

The specification (aka _spec_) is used to define your Dapp. This includes:

* The Dapp structure and layout.
* User input field validation settings.
* What contract methods to call.

We recommend storing your spec as a `.json` file in the same folder as your smart contracts.

Full example specs can be viewed via the [CLI](../../CommandLine).

## Structure

The general structure of a spec is as follows:

```js
{
  "version": ...,
  "id": "...",
  "title": "...",
  "description": "...",
  "image": { ... },
  "aboutUrl": "...",
  "constants": { ... },
  "panels": [ ... ]
}
```

## Reference

**version**

The spec version must always be 1. In future we may introduce non-backwards compatible changes which will require a change to this number.

Example:

```js
{
  "version": 1,
}
```

**id**

This should be a human-readable and identifier for your spec, e.g. `erc20-manager`. The supported characters are: `A-Z`, `a-z`, `0-9` and `-`. It must be between 3 and 32 characters in length.

If you decide to publish your spec to the solUI cloud then this id will also need to be unique relative to other Dapps you've already published.

Example:

```js
{
  "id": "erc20-token-ui",
}
```

**title**

A user-friendly title for your Dapp.  It must be between 3 and 256 characters in length.

Example:

```js
{
  "title": "Create and manage ERC-20 tokens",
}
```

**description** _(optional)_

A user-friendly text-only description for your Dapp. There is no character limit.

Example:

```js
{
  "description": "This interface is for creating and managing your own ERC-20 tokens."
}
```

**image** _(optional)_

An image which appears to display alongside the Dapp title.

Example:

```js
{
  "image": {
    "url": "https://url.to/logo.png"
  }
}
```

Base-64 `data:` URLs are also supported:

```js
{
  "image": {
    "url": "data:image/gif;base64,R0lGO..."
  }
}
```


**aboutUrl** _(optional)_

If set then the _About this app_ item will show in the bottom nav bar, linking to this URL:

![About app](../../images/AboutApp.png)

Example:

```js
{
  "aboutUrl": "https://github.com/solui/demo"
}
```


**constants** _(optional)_

The list of [named constants](../Constants).

Example:

```js
{
  "constants": {
    "tokenAddress": "0x12ab....",
    ...
  }
}
```


**panels**

Interface [panels](../Panels) which define the actual layout.

Example:

```js
{
  "panels": [
    { ... },
    { ... },
    ...
  ]
}
```


Overview

Named constants provide a method of re-using and sharing fixed string values throughout your Dapp. A named constant can be referenced as the initial value of an [input field](../Inputs) and also contract [execution](../Execs) parameters.

## Structure

```js
{
  ...,
  "constants": {
    "name1": "value1",
    "name2": {
      "default": "value2-default",
      "4": "value2-rinkeby",
      "3": "value2-ropsten",
      ...
    },
    ...
  },
}
```

## Reference

**How naming works**

Constants are specified as a mapping of key-value pairs contained within the top-level `constants` key.

The _key_ is the name of the constants. For example, given:

```js
"constants": {
  "firstName": "John"
}
```

The above constant can referenced anywhere within the Dapp spec using `@constant[firstName]`.

**How values are specified**

The _value_ of a constant can be specified as either:

* A fixed string
* A mapping of network id to strings

The above example uses a fixed stirng representation:

```js
"constants": {
  "firstName": "John"
}
```

An example of using a mapping:

```js
"constants": {
  "supply": {
    "default": "10",
    "4": "100",
    "3": "200"
  }
}
```

The above constant resolves to a different value depending on the Ethereum network the Dapp is currently being run on. If on the Rinkeby (network id = 4) the value will be `100`. On Ropsten (network id = 3) the value will be `200`. And all other networks (i.e. the `default`) the value will be `10`.

_Note: When using a mapping the `default` key-value pair MUST be specified_.

**How to use**

To refer to a constant, use the `@constants[name]` syntax, where `name` is the the actual constant name. See the docs for [inputs](../Inputs) for examples.


Constants

Panels are user interfaces which perform execution tasks.

<mockup here>

A panel display a single button to execute all the tasks and obtain the result.
It may also have user [input fields](../Inputs) to pass input arguments to the
[execution tasks](../Execs).

## Structure

```js
{
  ...,
  "panels": [
    {
      "id": "...",
      "title": "...",
      "inputs": [ ... ],
      "execs": [ ... ],
      "outputs": [ ... ]
    }
  ]
}
```

## Reference

**id**

This should be a human-readable and identifier for the panel, e.g. `deploy-token`. The supported characters are: `A-Z`, `a-z`, `0-9` and `-`. It must be between 3 and 32 characters in length.

This id must be unique amongst all the other panels in the spec.

Example:

```js
{
  "id": "create-token",
}
```

**title**

A user-friendly title for the panel.  It must be between 3 and 256 characters in length.

Example:

```js
{
  "title": "Create new token",
}
```

**inputs** _(optional)_

User [input fields](../Inputs) which define input arguments to pass to the
[execution tasks](../Execs).

```js
{
  "inputs": [
    { ... },
    { ... },
    ...,
  ]
}
```

**execs**

The [execution tasks](../Execs) to perform the when the panel gets executed.

The tasks are executed in sequence, one after another. This allows for earlier
tasks' outputs to be re-used as later tasks' inputs.

```js
{
  "execs": [
    { ... },
    { ... },
    ...,
  ]
}
```

**outputs** _(optional)_

The [outputs](../Outputs) to display to the user once panel tasks are successfully
executed.

Each output refers to the result of an [execution task](../Execs).

```js
{
  "outputs": [
    { ... },
    { ... },
    ...,
  ]
}
```


Panels

Inputs define the input fields that show in a panel.

Inputs have types, optional validation checks and ultimately feed into contract method arguments. By default
inputs are rendered in the order in which they're defined in a panel.

## Structure

```js
{
  ...,
  "panels": [
    {
      ...,
      "inputs": [
        {
          "name": "...",
          "title": "...",
          "initialValue": "...",
          "type": "...",
          "placeholder": "...",
          "helpText": "...",
          "unit": "...",
          "scale": "...",
          "validation": [ ... ]
        },
        ...
      ]
    }
  ]
}
```

## Reference

**name**

The name of the input. This is not shown to the user but is instead the canonical internal name of the input. It must be unique in the list of input names for its parent panel.

Example:

```js
{
  "name": "tokenName"
}
```

The above example's input value can be referenced elsewhere in the Dapp using `@input[tokenName]`.

**title**

The user-friendly name of the input. This is shown the user as the label for the input.

Example:

```js
{
  "title": "Token name"
}
```

**type**

The input type. At present this must be one of:

* `address`
* `bool`
* `bytes32`
* `int`
* `string`

Example:

```js
{
  "type": "bytes32"
}
```


**placeholder** _(optional)_

The placholder text.

Example:

```js
{
  "placeholder": "A non-zero number"
}
```


**helpText** _(optional)_

Help text to be displayed next to the input field to help clarify its use.

Example:

```js
{
  "helpText": "Please enter the desired totaly supply of your token."
}
```


**initialValue** _(optional)_

Initial value to display in the input field, specified as one of.

  * A named [constant](../Constants).
  * An [environment variable](../EnvVars).
  * A fixed string value.

Example using a fixed value:

```js
{
  "initialValue": "100"
}
```

Example using a named constant:

```js
{
  "initialValue": "@constant[contractAddress]"
}
```

Example using an environment variable:

```js
{
  "initialValue": "@env[account]"
}
```

**unit** _(optional)_

Applies to `type`: `int`

This is user-friendly text that gets shown in the tooltip
popup next to the input label:

![Field unit](../../images/FieldUnit.png)

Example:

```js
{
  "unit": "TOKEN"
}
```

**scale** _(optional)_

Applies to `type`: `int`

This is how to much to scale the input value by to obtain the real integer value. This
means multiplying the input value by `10^scale` to obtain the real value.

For example, if inputting an ETH value then the scale should be set to 18 to
ensure that the real value sent to the contract is measured in WEI.

Example:

```js
{
  "scale": 18
}
```

**validation** _(optional)_

List of [validation checks](../InputValidation) for this input field.

Example:

```js
{
  "validation": [
    {
      ...
      "type": "..."
    },
    ...
  ]
}
```


Inputs

Input validations define validation checks to be performed on input field values.

## Structure

```js
{
  ...,
  "panels": [
    {
      ...,
      "inputs": [
        {
          ...,
          "validation": [
            {
              "type": "length",
              "min": "2",
              "max": "10"
            },
            ...
          ]
        },
        ...
      ]
    }
  ]
}
```

## Reference

The `type` parameter specifies the input validation type:

* `length`
* `range`
* `allowedTypes`

Example:

```js
{
  "type": "length"
}
```

Additional attributes depend on the validation `type`.

**Validation: length**

The `length` validation checks the length of the input string to ensure its
within the range specified by `min` and `max`.

Example:

```js
{
  /* string must between 1 and 23 characters in length */
  "type": "length",
  "min": "1",
  "max": "23"
}
```

Example with just `min`:

```js
{
  /* string must atleast 5 characters in length */
  "type": "length",
  "min": "5"
}
```

Example with just `max`:

```js
{
  /* string must no more than 17 characters in length */
  "type": "length",
  "max": "17"
}
```

**Validation: range**

The `range` validation checks that the input string represents a number between
`min` and `max` boundary values. The boundary values can be positive or negative 256-bit integer values.

Example :

```js
{
  /* string must represent a number between -10 and 23 in value */
  "type": "range",
  "min": "-10",
  "max": "23"
}
```

Example with just `min`:

```js
{
  /* string must represent a number greater than or equal to 2 in value */
  "type": "range",
  "min": "2"
}
```

Example with just `max`:

```js
{
  /* string must represent a number less than or equal to -20 in value */
  "type": "range",
  "max": "-20"
}
```

**Validation: allowedTypes**

If the input type is `address` then this validation check specifies what types of
Ethereum addresses are allowed. Specifically there are two address types:

* `contract` - an on-chain contract address.
* `eoa` - an "externally-owned account", i.e. a standard Ethereum address that isn't an on-chain contract.

Examples:

```js
{
  /* address must be a contract address, not an eoa */
  "type": "allowedTypes",
  "contract": true
}
```

```js
{
  /* address can be either an eoa or contract address */
  "type": "allowedTypes",
  "contract": true,
  "eoa": true
}
```

Input validation

Execution tasks define what contract methods get called with what arguments.

If a [panel](../Panels) defines more than one execution task they are
executed in _sequence_, not parallel.
This allows for the output of an earlier task to be re-used as the input argument of a later task.

## Structure

```js
{
  ...,
  "panels": [
    {
      ...,
      "execs": [
        {
          "type": "...",
          "contract": "...",
          "address": "...",
          "method": "...",
          "args": { ... },
          "saveResultAs": "..."
        }
      ]
    }
  ]
}
```

## Reference

**type**

The type of contract call to make. Can be one of:

* `deploy` - deploy a contract. _Note: The `method` property is
ignored in this case_.
* `call` - call a read-only method on a contract without creating a
transaction (equivalent to [eth_call](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_call)).
* `send` - call a method on a contract by creating a
transaction (equivalent to [eth_sendTransaction](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_call)).

Example:

```js
{
  "type": "send"
}
```

**contract**

The name of the contract, present in the list of [contract artifacts](../../CommandLine/View).

Example:

```js
{
  "name": "ERC20"
}
```

**address**

The on-chain address of the contract, specified as one of:

  * Name of a panel [input field](../Inputs).
  * A named [constant](../Constants).
  * An [environment variable](../EnvVars).
  * The result of a previous execution task (see `saveResultAs` below).
  * A fixed value.

Example (address is specified as a user input field):

```js
{
  "inputs": [
    { name: "contractAddress", ... },
    ...
  ],
  "execs": [
    {
      ...,
      "address": "@input[contractAddress]"
    }
  ]
}
```

Example (address is specified as a named constant):

```js
{
  "execs": [
    {
      ...,
      "address": "@constant[contractAddress]"
    }
  ]
}
```

Example (address is specified as result of earlier task):

```js
{
  "execs": [
    /* this gets executed first */
    {
      ...,
      "saveResultAs": "contractAddress"
    },
    /* this gets executed second */
    {
      ...,
      "address": "@input[contractAddress]"
    }
  ]
}
```

**method**

The method to call on the contract. The method must be externally callable.

Example:

```js
{
  "method": "transfer"
}
```

_Note: If execution `type` equals `deploy` then this property is ignored_.

**args** _(optional)_

The arguments to pass to the contract method.

This is specified as key-value pairs, where the key is the name of contract
method argument and corresponding value is one of:

  * Name of a panel [input field](../Inputs).
  * A named [constant](../Constants).
  * An [environment variable](../EnvVars).
  * The named result of a previous execution task (see `saveResultAs` below).
  * A fixed value.

Example:

```js
{
  "inputs": [
    { name: "name", ... },
    { name: "symbol", ... },
    { name: "initialSupply", ... }
  ],
  "execs": [
   {
     "type": "deploy",
     "contract": "ERC20",
     "args": {
       "_name": "@constant[tokenName]",
       "_symbol": "@input[symbol]",
       "_initialSupply": "1000000"
     }
   }
  ]
}
```

Example using an environment variable:

```js
{
  "execs": [
    {
      "type": "call",
      "method": "balanceOf",
      "args": {
        "_address": "@env[account]",
      }
      ...,
    }
  ]
}
```

Example mapping from result of previous execution:

```js
{
  "execs": [
    {
      "type": "deploy",
      ...,
      "saveResultAs": "newContractAddress",
    },
    {
      "type": "send",
      "method": "setTokenContract",
      "args": {
        "_address": "@input[newContractAddress]",
      }
      ...,
    }
  ]
}
```

**saveResultAs** _(optional)_

Save the result of the execution as a named variable to used as an input later
on.

Example:

```js
{
  "execs": [
    {
      "type": "call",
      ...,
      "saveResultAs": "currentBalance",
    },
    {
      "type": "send",
      "method": "transfer",
      "args": {
        "_amount": "@input[currentBalance]",
      }
      ...,
    }
  ]
}
```


Execs

Outputs specify results to display to the user once panel has succesfully executed. If no outputs are defined then the Dapp will not display any results but will simply show a success status.

![Outputs](../../images/Outputs.png)

## Structure

```js
{
  ...,
  "panels": [
    {
      ...,
      "execs": [ ... ],
      "outputs": [
        {
          "title": "...",
          "type": "...",
          "value": "...",
          "scale": "...",
          "unit": "...",
        },
        ...
      ]
    }
  ]
}
```

Note that outputs are only displayed once all [Execution steps](../Execs) have been completed.

## Reference

**type**

The output type. This is to help the renderer figure out how best to display the output value. At present this must be one of:

* `address`
* `bool`
* `bytes32`
* `int`
* `string`

Example:

```js
{
  "type": "string"
}
```

**title**

The user-friendly label for this output value.

Example:

```js
{
  "title": "Balance"
}
```

**value**

The value to display, specified as one of:

* Reference to a panel [input field](../Inputs).
* Reference to a previous [execution result](../Execs)
* A fixed value.

Examples:

```js
{
  "value": "@input[tokenSymbol]"
}
```

```js
{
  "value": "A fixed value"
}
```

**scale** _(optional)_

Applies to `type`: `int`

This is how to much to scale the output value by to obtain the displayable value. This
means multiplying the input value by `10^scale` to obtain the real value.

For example, if outputting an ETH value (which gets returned as WEI from a contract call)
then the scale should be set to -18.

Example:

```js
{
  "scale": "-18"
}
```

If a scale is set then the output value becomes clickable such that the user is able to
cycle through the different formats (both scaled and unscaled):

![Output value](../../images/OutputValue.png)

**unit** _(optional)_

Applies to `type`: `int`

This is user-friendly text that gets shown next to the output value when the `scale` property is also set.

Example:

```js
{
  "unit": "Tokens"
}
```



Outputs

Some built-in environment variables are available for use in a Dapp spec. They function in a similar way to [constants](../Constants) in that they are constant, unchange-able values. The difference is that they are automatically available and do not have to be explicitly declared.


## Reference

At present the following environment variables are available:

* `account` - the user's account address, i.e. the active Metamask account or the active address in their connected wallet

**How to use**

To refer to a constant, use the `@env[name]` syntax, where `name` is the the actual constant name. See the docs for [inputs](../Inputs) for examples.


Environment

Specification

Use the `version` command to obtain the current solui package version:

```shell
solui version
```
