embark/site/source/docs/embark_commands.md

179 lines
4.9 KiB
Markdown
Raw Normal View History

2019-04-18 12:33:52 +02:00
title: Embark CLI Commands
layout: docs
---
This is the Embark CLI command reference.
## new
```
$ embark new dappName
```
Creates a new empty DApp project. If no `dappName` is provided, Embark will ask for the dappName.
Option | Description
--- | ---
`--contracts-only` | create a barebones project meant only for contract development
`--simple` | an alias for `--contracts-only`
`--template` | **DEPRECATED IN v5** download a template using a known name or a git host URL
{% notification danger 'DEPRECATION NOTICE' %}
The `--template` option has been deprecated in v5 and support will be removed in future versions.
{% endnotification %}
2019-04-18 12:33:52 +02:00
The `--template` option supports several URL styles and shortcuts for git hosts:
```
git@github.com:ghuser/repo_name
https://github.com/ghuser/repo_name
github:ghuser/repo_name
ghuser/repo_name
```
It's possible to append a branch name to any of the above, for example:
```
https://github.com/ghuser/repo_name#branch_name
ghuser/repo_name#branch_name
```
Bitbucket and GitLab URLs and shortcuts are also supported, for example:
```
bitbucket:bbuser/repo_name#branch_name
gitlab:gluser/repo_name#branch_name
```
A short name can be used for templates maintained in the Embark GitHub organization, for example:
```
$ embark new --template typescript
```
## demo
```
$ embark demo
```
Generates a demo Embark Project with a working contract and examples of working with contracts, IPFS and Whisper.
## build
```
$ embark build [environment]
```
Deploys and Builds the DApp at dist/. If no `environment` is provider embark will use `development` by default.
## run
```
$ embark run [environment]
```
Deploys and Builds the DApp at `dist/`. By default will launch a dashboard and start a dev server at `http://localhost:8000/`. If no `environment` is provider embark will use `development` by default.
Option | Description
--- | ---
`-p`, `--port` | `port` to run the dev webserver (default: 8000)
`-b`, `--host` | `host` to run the dev webserver (default: localhost)
`--noserver` | disable the development webserver
`--nodashboard` | simple mode, disables the dashboard
`--nobrowser` | prevent the development webserver from automatically opening a web browser
`--no-color` | no colors in case it's needed for compatbility purposes
`--logfile` | `filename` to output logs (default: none)
## blockchain
```
$ embark blockchain [environment]
```
Takes the config at `config/blockchain.json` for the `environment` specified and starts a blockchain node. If no `environment` is provider embark will use `development` by default.
If you want, you can skip the step of running `embark blockchain`, as `embark run`, `build` and `upload` now all start a blockchain node in a separate process if there is not one already started using the same configurations.
## simulator
```
$ embark simulator [environment]
```
Takes the config at `config/blockchain.json` for the `environment` specified and starts a blockchain simulator. If no `environment` is provider embark will use `development` by default.
Option | Description
--- | ---
`-p`, `--port` | `port` to run the rpc simulator (default: 8545)
`-h`, `--host` | `host` to run the rpc simulator (default: localhost)
`-a`, `--accounts` | `num` of accounts to start the simulator (default: 10)
`-e`, `--defaultBalanceEther` | `balance` in ether to assign each test account (default: 100)
`-l`, `--gasLimit` | custom `gasLimit` (default: 8000000)
## test
```
$ embark test [file]
```
Runs Tests. If `file` is not specified then it will run all the tests inside the `test/` directory.
Option | Description
--- | ---
`-n`, `--node` | node for running the tests (default: vm)
`-d`, `--gasDetails` | print the gas cost for each contract deployment when running the tests
`-c`, `--coverage` | generate a coverage report after running the tests (vm only)
The `--node` option supports several values:
Value | Description
--- | ---
`vm` | start and use an Ethereum simulator (ganache)
`embark` | use the node of a running embark process
`<endpoint>` | connect to and use the specified node
Example of endpoint usage: `embark test --node ws://localhost:8556`
## reset
```
$ embark reset
```
Resets embarks state on this dapp including clearing cache.
feat(plugins/scripts-runner): introduce exec command to run scripts This commit introduces a new feature that enables users to run (migration) scripts. Similar to deployment hooks, scripts are functions that may perform operations on newly deployed Smart Contracts. Therefore a script needs to export a function that has access to some dependencies: ``` // scripts/001-some-script.js module.exports = async ({contracts, web3, logger}) => { ... }; ``` Where `contracts` is a map of newly deployed Smart Contract instances, `web3` a blockchain connector instance and `logger` Embark's logger instance. Script functions can but don't have to be `async`. To execute such a script users use the newly introduced `exec` command: ``` $ embark exec development scripts/001-some-script.js ``` In the example above, `development` defines the environment in which Smart Contracts are being deployed to as well as where tracking data is stored. Alternativey, users can also provide a directory in which case Embark will try to execute every script living inside of it: ``` $ embark exec development scripts ``` Scripts can fail and therefore emit an error accordingly. When this happens, Embark will abort the script execution (in case multiple are scheduled to run) and informs the user about the original error: ``` .. 001_foo.js running.... Script '001_foo.js' failed to execute. Original error: Error: Some error ``` It's recommended for scripts to emit proper instances of `Error`. (Migration) scripts can be tracked as well but there are a couple of rules to be aware of: - Generally, tracking all scripts that have been executed by default is not a good thing because some scripts might be one-off operations. - OTOH, there might be scripts that should always be tracked by default - Therefore, we introduce a dedicated `migrations` directory in which scripts live that should be tracked by default - Any other scripts that does not live in the specified `migrations` directory will not be tracked **unless** - The new `--track` option was provided For more information see: https://notes.status.im/h8XwB7xkR7GKnfNh6OnPMQ
2020-02-04 11:47:12 +01:00
## exec
```
$ embark exec [environment] [file|directory]
```
Executes a given (migration) script to perform complex after deployment operations.
It's required to specifiy the `environment` in which the script(s) will be executed in. In addition it's possible to specificy a directory in which multiple script live in. Embark will execute them one by one.
2019-04-18 12:33:52 +02:00
## upload
```
$ embark upload [platform] [environment]
```
Uploads the DApp to a decentralized storage such as IPFS. `platform` can be `ipfs` or `swarm` or another parameter if supported by a plugin. If no `environment` is provider embark will use `development` by default.
## graph
```
$ embark graph
```
Generates documentation based on the smart contracts configured
## version
```
$ embark version
```
Displays version information.