Home

Awesome

<p align="center"> <em>NOTICE</em>: <code>testrpc</code> is now <code>ganache-cli</code>. Use it just as you would <code>testrpc</code>. </p> <hr/>

npm npm Build Status

<p align="center"> <img src="https://github.com/trufflesuite/ganache-cli/raw/develop/resources/icons/ganache-cli-128x128.png"> </p>

Welcome to Ganache CLI

Ganache CLI, part of the Truffle suite of Ethereum development tools, is the command line version of Ganache, your personal blockchain for Ethereum development.

Ganache CLI uses ethereumjs to simulate full client behavior and make developing Ethereum applications faster, easier, and safer. It also includes all popular RPC functions and features (like events) and can be run deterministically to make development a breeze.

Looking for TestRPC?

If you came here expecting to find the TestRPC, you're in the right place! Truffle has taken the TestRPC under its wing and made it part of the Truffle suite of tools. From now on you can expect better support along with tons of new features that help make Ethereum development safer, easier, and more enjoyable. Use ganache-cli just as you would testrpc.

Installation

ganache-cli is written in JavaScript and distributed as a Node.js package via npm. Make sure you have Node.js (>= v8) installed.

Using npm:

npm install -g ganache-cli

or, if you are using Yarn:

yarn global add ganache-cli

ganache-cli utilizes ganache-core internally, which is distributed with optional native dependencies for increased performance. If these native dependencies fail to install on your system ganache-cli will automatically fallback to ganache-core’s pre-bundled JavaScript build.

Having problems? Be sure to check out the FAQ and if you're still having issues and you're sure its a problem with ganache-cli please open an issue.

Using Ganache CLI

Command Line

$ ganache-cli <options>

Options:

Special Options:

Usage

As a Web3 provider:

const ganache = require("ganache-core");
const web3 = new Web3(ganache.provider());

If web3 is already initialized:

const ganache = require("ganache-core");
web3.setProvider(ganache.provider());

NOTE: depending on your web3 version, you may need to set a number of confirmation blocks

const web3 = new Web3(provider, null, { transactionConfirmationBlocks: 1 });

As an ethers.js provider:

const ganache = require("ganache-cli");
const provider = new ethers.providers.Web3Provider(ganache.provider());

As a general HTTP and WebSocket server:

const ganache = require("ganache-cli");
const server = ganache.server();
server.listen(port, function(err, blockchain) {...});

Options

Both .provider() and .server() take a single object which allows you to specify behavior of ganache-cli. This parameter is optional. Available options are:

Implemented Methods

The RPC methods currently implemented are:

Management API Methods

Custom Methods

Special non-standard methods that aren’t included within the original RPC specification:

Unsupported Methods

Docker

The Simplest way to get started with the Docker image:

docker run --detach --publish 8545:8545 trufflesuite/ganache-cli:latest

To pass options to ganache-cli through Docker simply add the arguments to the run command:

docker run --detach --publish 8545:8545 trufflesuite/ganache-cli:latest --accounts 10 --debug
                                                                        ^^^^^^^^^^^^^^^^^^^^^

The Docker container adds an environment variable DOCKER=true; when this variable is set to true (case insensitive), ganache-cli use a default hostname IP of 0.0.0.0 instead of the normal default 127.0.0.1. You can still specify a custom hostname however:

docker run --detach --publish 8545:8545 trufflesuite/ganache-cli:latest --host XXX.XXX.XXX.XXX
                                                                        ^^^^^^^^^^^^^^^^^^^^^^

To build and run the Docker container from source:

git clone https://github.com/trufflesuite/ganache-cli.git && cd ganache-cli

then:

docker build --tag trufflesuite/ganache-cli .
docker run --publish 8545:8545 trufflesuite/ganache-cli

or

npm run docker

Contributing to Ganache CLI

The Ganache CLI repository contains the cli logic and Docker config/build only. It utilizes ganache-core, the core logic powering Ganache, internally.

You can contribute to the core code at ganache-core.

To contribue to ganache-cli, run:

git clone https://github.com/trufflesuite/ganache-cli.git && cd ganache-cli
npm install

You'll need Python 2.7 installed, and on Windows, you'll likely need to install windows-build-tools from an Administrator PowerShell Prompt via npm install --global windows-build-tools.

PR Message format:

<type>(<scope>): <subject>

Where type must be one of the following:

see: https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines

License

MIT