<divclass="link title"><ahref="/v5/">Documentation</a></div><divclass="base show link depth-1"><ahref="/v5/getting-started/">Getting Started</a></div><divclass="base show link depth-1"><ahref="/v5/concepts/">Ethereum Basics</a></div><divclass="hide link depth-2"><ahref="/v5/concepts/events/">Events</a></div><divclass="hide link depth-2"><ahref="/v5/concepts/gas/">Gas</a></div><divclass="hide link depth-2"><ahref="/v5/concepts/security/">Security</a></div><divclass="base show link depth-1"><ahref="/v5/api/">Application Programming Interface</a></div><divclass="hide link depth-2"><ahref="/v5/api/contract/">Contract Interaction</a></div><divclass="hide link depth-3"><ahref="/v5/api/contract/contract/">Contract</a></div><divclass="hide link depth-3"><ahref="/v5/api/contract/contract-factory/">ContractFactory</a></div><divclass="hide link depth-3"><ahref="/v5/api/contract/example/">Example: ERC-20 Contract</a></div><divclass="hide link depth-2"><ahref="/v5/api/signer/">Signers</a></div><divclass="hide link depth-2"><ahref="/v5/api/providers/">Providers</a></div><divclass="hide link depth-3"><ahref="/v5/api/providers/provider/">Provider</a></div><divclass="hide link depth-3"><ahref="/v5/api/providers/jsonrpc-provider/">JsonRpcProvider</a></div><divclass="hide link depth-3"><ahref="/v5/api/providers/api-providers/">API Providers</a></div><divclass="hide link depth-3"><ahref="/v5/api/providers/other/">Other Providers</a></div><divclass="hide link depth-3"><ahref="/v5/api/providers/types/">Types</a></div><divclass="hide link depth-2"><ahref="/v5/api/utils/">Utilities</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/abi/">Application Binary Interface</a></div><divclass="hide link depth-4"><ahref="/v5/api/utils/abi/interface/">Interface</a></div><divclass="hide link depth-4"><ahref="/v5/api/utils/abi/fragments/">Fragments</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/address/">Addresses</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/bignumber/">BigNumber</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/bytes/">Byte Manipulation</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/constants/">Constants</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/display-logic/">Display Logic and Input</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/encoding/">Encoding Utilities</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/fixednumber/">FixedNumber</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/hashing/">Hashing Algorithms</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/hdnode/">HD Wallet</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/logger/">Logging</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/properties/">Property Utilities</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/signing-key/">Signing Key</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/strings/">Strings</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/transactions/">Transactions</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/web/">Web Utilities</a></div><divclass="hide link depth-3"><ahref="/v5/api/utils/wordlists/">Wordlists</a></div><divclass="hide link depth-2"><ahref="/v5/api/other/">Other Libraries</a></div><divclass="hide link depth-3"><ahref="/v5/api/other/assembly/">Assembly</a></div><divclass="hide link depth-4"><ahref="/v5/api/other/assembly/dialect/">Ethers ASM Dialect</a></div><divclass="hide link depth-4"><ahref="/v5/api/other/assembly/api/">Utilities</a></div><divclass="hide link depth-4"><ahref="/v5/api/other/assembly/ast/">Abstract Syntax Tree</a></div><divclass="hide link depth-3"><ahref="/v5/api/other/hardware/">Hardware Wallets</a></div><divclass="hide link depth-2"><ahref="/v5/api/experimental/">Experimental</a></div><divclass="base ancestor show link depth-1"><ahref="/v5/cli/">Command Line Interfaces</a></div><divclass="show link depth-2"><ahref="/v5/cli/e
<divclass="breadcrumbs"><ahref="/v5/">Documentation</a> » <ahref="/v5/cli/">Command Line Interfaces</a> » <spanclass="current">Making Your Own</span></div>
<aname="cli-diy"></a><aname="cli-diy"></a><h1class="show-anchors"><div>Making Your Own<divclass="anchors"><aclass="self"href="/v5/cli/plugin/#cli-diy"></a></div></div></h1><p>The <i>cli</i> library is meant to make it easy to create command line utilities of your own.</p>
<aname="cli-cli"></a><aname="cli-diy--cli-cli"></a><h2class="show-anchors"><div>CLI<divclass="anchors"><aclass="self"href="/v5/cli/plugin/#cli-cli"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L715">source</a></div></div></h2><p>A <b>CLI</b> handles parsing all the command-line flags, options and arguments and instantiates a <ahref="/v5/cli/plugin/#cli-plugin">Plugin</a> to process the command.</p>
<p>A <b>CLI</b> may support multiple <ahref="/v5/cli/plugin/#cli-plugin">Plugin</a>'s in which case the first argument is used to determine which to run (or if no arguments, the default plugin will be selected) or may be designed to be standalone, in which case exactly one <ahref="/v5/cli/plugin/#cli-plugin">Plugin</a> will be used and no command argument is allowed.</p>
<aname="cli-addplugin"></a><divclass="property show-anchors"><divclass="signature"><spanclass="method">addPlugin</span><spanclass="symbol">(</span><spanclass="param">command</span><spanclass="symbol">,</span><spanclass="param">pluginClass</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#cli-addplugin"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L755">source</a></div></div><divclass="body"><p>Add a <i>plugin</i> class for the <i>command</i>. After all options and flags have been consumed, the first argument will be consumed and the associated plugin class will be instantiated and run.</p>
</div></div><aname="cli-setplugin"></a><divclass="property show-anchors"><divclass="signature"><spanclass="method">setPlugin</span><spanclass="symbol">(</span><spanclass="param">pluginClass</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#cli-setplugin"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L769">source</a></div></div><divclass="body"><p>Set a dedicated <ahref="/v5/cli/plugin/#cli-plugin">Plugin</a> class which will handle all input. This may not be used in conjuction with addPlugin and will not automatically accept a command from the arguments.</p>
</div></div><aname="cli-showusage"></a><divclass="property show-anchors"><divclass="signature"><spanclass="method">showUsage</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">message</span> = "" <spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">status</span> = <spanclass="param">0</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">never</span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#cli-showusage"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L783">source</a></div></div><divclass="body"><p>Shows the usage help screen for the CLI and terminates.</p>
</div></div><aname="cli-run"></a><divclass="property show-anchors"><divclass="signature"><spanclass="method">run</span><spanclass="symbol">(</span><spanclass="param">args</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< void ></span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#cli-run"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L910">source</a></div></div><divclass="body"><p>Usually the value of <i>args</i> passed in will be <codeclass="inline">process.argv.slice(2)</code>.</p>
</div></div><aname="cli-plugin"></a><aname="cli-diy--cli-plugin"></a><h2class="show-anchors"><div>Plugin<divclass="anchors"><aclass="self"href="/v5/cli/plugin/#cli-plugin"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L490">source</a></div></div></h2><p>Each <b>Plugin</b> manages each command of a CLI and is executed in phases.</p>
<p>If the usage (i.e. help) of a CLI is requested, the static methods <codeclass="inline">getHelp</code> and <codeclass="inline">getOptionHelp</code> are used to geneate the help screen.</p>
<p>Otherwise, a plugin is instantiated and the <codeclass="inline">prepareOptions</code> is called. Each plugin <b>must</b> call <codeclass="inline">super.prepareOptions</code>, otherwise the basic options are not yet processed. During this time a Plugin should consume all the flags and options it understands, since any left over flags or options will cause the CLI to bail and issue an <i>unknown option</i> error. This should throw if a value for a given option is invalid or some combination of options and flags is not allowed.</p>
<p>Once the prepareOptions is complete (the returned promise is resolved), the <codeclass="inline">prepareArguments</code> is called. This should validate the number of arguments is expected and throw and error if there are too many or too few arguments or if any arguments do not make sense.</p>
<p>Once the prepareArguments is complete (the returned promise is resolved), the <codeclass="inline">run</code> is called.</p>
<divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">network</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="/v5/api/providers/types/#providers-Network">Network</a></span><divclass="anchors"></div></div><divclass="body"><p>The network this plugin is running for.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">provider</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="/v5/api/providers/provider/">Provider</a></span><divclass="anchors"></div></div><divclass="body"><p>The provider for this plugin is running for.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">accounts</span><spanclass="arrow">⇒</span><spanclass="returns">Array<<ahref="/v5/api/signer/#Signer">Signer</a>></span><divclass="anchors"></div></div><divclass="body"><p>The accounts passed into the plugin using <codeclass="inline">--account</code>, <codeclass="inline">--account-rpc</code> and <codeclass="inline">--account-void</code> which this plugin can use.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">gasLimit</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>The gas limit this plugin should use. This is null if unspecified.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">gasPrice</span><spanclass="arrow">⇒</span><spanclass="returns"><ahref="/v5/api/utils/bignumber/">BigNumber</a></span><divclass="anchors"></div></div><divclass="body"><p>The gas price this plugin should use. This is null if unspecified.</p>
</div></div><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">nonce</span><spanclass="arrow">⇒</span><spanclass="returns">number</span><divclass="anchors"></div></div><divclass="body"><p>The initial nonce for the account this plugin should use.</p>
</div></div><aname="plugin-getaddress"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">getAddress</span><spanclass="symbol">(</span><spanclass="param">addressOrName</span><spanclass="symbol">[</span><spanclass="symbol">,</span><spanclass="param">message</span> = "" <spanclass="symbol">,</span><spanclass="symbol">[</span><spanclass="param">allowZero</span> = <spanclass="param">false</span><spanclass="symbol">]</span><spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Promise< string ></span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#plugin-getaddress"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L663">source</a></div></div><divclass="body"><p>A plugin should use this method to resolve an address. If the resovled address is the zero address and <i>allowZero</i> is not true, an error is raised.</p>
</div></div><aname="plugin-dump"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">dump</span><spanclass="symbol">(</span><spanclass="param">header</span><spanclass="symbol">,</span><spanclass="param">info</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">void</span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#plugin-dump"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L682">source</a></div></div><divclass="body"><p>Dumps the contents of <i>info</i> to the console with a <i>header</i> in a nicely formatted style. In the future, plugins may support a JSON output format which will automatically work with this method.</p>
</div></div><aname="plugin-throwusageerror"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">throwUsageError</span><spanclass="symbol">(</span><spanclass="symbol">[</span><spanclass="param">message</span> = "" <spanclass="symbol">]</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">never</span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#plugin-throwusageerror"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L688">source</a></div></div><divclass="body"><p>Stops exectuion of the plugin and shows the help screen of the plugin with the optional <i>message</i>.</p>
</div></div><aname="plugin-throwerror"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">plugin</span><spanclass="symbol">.</span><spanclass="method">throwError</span><spanclass="symbol">(</span><spanclass="param">message</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">never</span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#plugin-throwerror"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L693">source</a></div></div><divclass="body"><p>Stops execution of the plugin and shows <i>message</i>.</p>
<aname="plugin-gethelp"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">Plugin</span><spanclass="symbol">.</span><spanclass="method">getHelp</span><spanclass="arrow">⇒</span><spanclass="returns">Help</span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#plugin-gethelp"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L507">source</a></div></div><divclass="body"><p>Each subclass should implement this static method which is used to generate the help screen.</p>
</div></div><aname="plugin-getoptionshelp"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">Plugin</span><spanclass="symbol">.</span><spanclass="method">getOptionHelp</span><spanclass="arrow">⇒</span><spanclass="returns">Array< Help ></span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#plugin-getoptionshelp"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L511">source</a></div></div><divclass="body"><p>Each subclass should implement this static method if it supports additional options which is used to generate the help screen.</p>
</div></div><aname="cli-argparser"></a><aname="cli-diy--cli-argparser"></a><h2class="show-anchors"><div>ArgParser<divclass="anchors"><aclass="self"href="/v5/cli/plugin/#cli-argparser"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L292">source</a></div></div></h2><p>The <b>ArgParser</b> is used to parse a command line into flags, options and arguments.</p>
# - [ "send", "ricmoo.eth", "1.0" ]</div><p>Flags are simple binary options (such as the <codeclass="inline">--yes</code>), which are true if present otherwise false.</p>
<p>Options require a single parameter follow them on the command line (such as <codeclass="inline">--account wallet.json</code>, which nhas the name <codeclass="inline">account</code> and the value <codeclass="inline">wallet.json</code>)</p>
<p>Arguments are all other values on the command line, and are not accessed through the <b>ArgParser</b> directly.</p>
<p>When a CLI is run, an <b>ArgParser</b> is used to validate the command line by using prepareOptions, which consumes all flags and options leaving only the arguments behind, which are then passed into prepareArgs.</p>
<aname="argparser-consumeflag"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">argParser</span><spanclass="symbol">.</span><spanclass="method">consumeFlag</span><spanclass="symbol">(</span><spanclass="param">name</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">boolean</span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#argparser-consumeflag"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L333">source</a></div></div><divclass="body"><p>Remove the flag <i>name</i> and return true if it is present.</p>
</div></div><aname="argparser-consumemultioptions"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">argParser</span><spanclass="symbol">.</span><spanclass="method">consumeMultiOptions</span><spanclass="symbol">(</span><spanclass="param">names</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Array< {name:string,value:string} ></span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#argparser-consumemultioptions"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L351">source</a></div></div><divclass="body"><p>Remove all options which match any name in the Array of <i>names</i> with their values returning the list (in order) of values.</p>
</div></div><aname="argparser-consumeoption"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">argParser</span><spanclass="symbol">.</span><spanclass="method">consumeOption</span><spanclass="symbol">(</span><spanclass="param">name</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">string</span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#argparser-consumeoption"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L380">source</a></div></div><divclass="body"><p>Remove the option with its value for <i>name</i> and return the value. This will throw a UsageError if the option is included multiple times.</p>
</div></div><aname="argparser-consumeoptions"></a><divclass="property show-anchors"><divclass="signature"><spanclass="path">argParser</span><spanclass="symbol">.</span><spanclass="method">consumeOptions</span><spanclass="symbol">(</span><spanclass="param">name</span><spanclass="symbol">)</span><spanclass="arrow">⇒</span><spanclass="returns">Array< string ></span><divclass="anchors"><aclass="self"href="/v5/cli/plugin/#argparser-consumeoptions"></a><aclass="source"href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/cli/src.ts/cli.ts#L376">source</a></div></div><divclass="body"><p>Remove all options with their values for <i>name</i> and return the list (in order) of values.</p>
<divclass="copyright">The content of this site is licensed under the <ahref="https://choosealicense.com/licenses/cc-by-4.0/">Creative Commons License</a>. Generated on June 10, 2020, 12:47am.</div>
