Command Line Tools

Skip to Commands

hcadmin init
hcadmin join
hcadmin bridge
hcadmin status
hcadmin dump
hcd
hcdev init
hcdev test
hcdev scenario
hcdev web
hcdev package
hcdev dump

 

Introduction

Now that Holochain and the command line tools are installed, we can cover how to run and how to develop Holochain applications, both of which are done through the command line tools at this point. 

An introduction to the commands necessary for some of the most common use cases are here. Below those use cases is the complete documentation list for the command line tools.

I want to start developing a new Holochain application

I want to start to use and run a Holochain application

HoloWorld Tutorial: Creating the App Folder

Knowing the commands mentioned in those use cases will get you a long ways, and learning the rest of the commands will come with time as you get into more advanced use cases. Now that the command line tools are more familiar, you can get into the details of configuring, and understanding, the "DNA" of your application

 

Command Documentation

 

hcadmin

The hcadmin is a command line tool for administering Holochain applications.

hcadmin init

hcadmin init <agent-id-string>

This command initializes the Holochain environment, and must be run before you install or run chains. You must provide a unique agent identification, usually an e-mail, as an argument to this command.

This command initializes the system with a default identity and generates default public/private keys for interacting with other networked peers. You provide a single string of identifying information which will be provided to the application as your agent_name. This is often an email address.

This command creates a ~/.holochain directory (by default, which you can override with the --path flag) where all your holochain data will be stored.

 

hcadmin join

hcadmin join <path-to-holochain-source> <chain-name>

Joins a holochain by installing an instance from an app package (or source directory) and generating genesis entries.

Note: Use `HOLOCHAINCONFIG_PORT` for changing the default config for "Port" that goes in `config.json`.
Read more on https://developer.holochain.org/Environment_Variables

 

hcadmin bridge

hcadmin bridge <from-chain-name> <to-chain-name> [--bridgeFromAppData <data>] [--bridgeToAppData <data>]

Bridging allows the from chain to make calls to the to chain if they were designed to do so. For example our holochat application can be bridged to our dpki app for identity management.

 

hcadmin status

hcadmin status

See what holochains are installed on your system. Result shows each chain name and the ID/hash of the DNA of the chain.

For example, results should look something like this:

installed holochains:
     escrow QmT6cuoNgGUxWwa9bHsKeyhEW2VmJPWc1DgKfVU6ehjkjE 
     flack Qm9yPX4cX3hA9DNkx6kNjdKRmPLdDZeJrPcWChpLv6X7PG

 

hcadmin dump

hcadmin dump <chain-name> --chain

Dumps the contents of a holochain chain.

hcadmin dump <chain-name> --dht

Dumps the contents of a holochain DHT.

Use --jsonto output the results as JSON.

 

hcd

hcd

hcd <chain-name> <port> 

run to start a web server for [chain-name]. [chain-name] needs to be one of the chains listed by the$ hcadmin status command. Default port is 3141

E.g.

$ hcd clutter 3142

Output: 

Serving holochain with DNA hash:QmbsfV4ZgK3E4XyHZaiar6FPUvqBaSgd93rVWPhPA5WKn3 on port 3142

 

hcdev

The hcdev command is a tool for holochain application development. It provides developers a convenient way to run tests and serve chains while in development. You should be inside the directory of the application you want to run in dev mode when you use the hcdev command.

expand_more Usage notes
The hcdev command doesn't use the ~/.holochain directory used by hcd and hcadmin, instead it runs your chain by default in ~/.holochaindev. You can override ...

hcdev init

hcdev init [command options] <app-name>

Initialize a holochain app directory:  from a appPackage file or clone from another app. This will create an empty directory hierarchy with a minimal DNA file in dna/dna.json.  Note that you can supply a path for `<app-name>` and the base of the path will be used as the app's name.

expand_more hcdev init options
OPTIONS: --test initialize built-in testing app --clone value path from which to clone the app --package value path to an app package file from which ...

 

hcdev test

hcdev test [test-name]

This command runs all the stand-alone tests in the test subdirectory for the holochain in the current working directory. You can also optionally just specify a single test file to test. Please see the Test Driven Development section for documentation on how to write tests.

When you need to bridge in your scenarios add a bridge_specs.json file in the root directory of the app.  You can also use the -bridgeSpecs flag to specify a bridge specs file by path, or you can use the value "_" disable bridging.

The format of the bridge_specs.json file is an array of objects of this form:

 {
        Path:                    string // path to the app to bridge to/from
        Side:                    int    // what side of the bridge the dev app is (Bridge.Caller or Bridge.Callee)
        BridgeGenesisCallerData: string // genesis data for the caller side
        BridgeGenesisCalleeData: string // genesis data for the callee side
        Port:                    string // only used if side == BridgeCallee
        BridgeZome:              string // only used if side == BridgeCaller
}

 

hcdev scenario

hcdev scenario <scenario-name>

This command runs the multi-node scenario testing harness. <scenario-name> should be a scenario from your test directory. Please see the Test Driven Development section for documentation on how to write scenario tests.

When you need to bridge in your scenarios you can:

  • add a bridge_specs.json file in the root directory of the app or you can use the -bridgeSpecs flag to override this behavior and either give it a path to the file, or the value "_" which will then not do the bridging
  • create per-role bridge specs in  the scenario's directory using the folloowing naming convention: _<role>_bridge_specs.json The scenrio will use that file (instead of the default bridge specs) for setting up bridging for the given role (and all it's clones) if it exists.

The format of a bridge_specs.json file is an array of objects of this form:

 {
        Path:                    string // path to the app to bridge to/from
        Side:                    int    // what side of the bridge the dev app is (Bridge.Caller or Bridge.Callee)
        BridgeGenesisCallerData: string // genesis data for the caller side
        BridgeGenesisCalleeData: string // genesis data for the callee side
        Port:                    string // only used if side == BridgeCallee
        BridgeZome:              string // only used if side == BridgeCaller
}


 

hcdev web

hcdev web [port]

Launches an http-POST based, or websockets API, which provides access to exposed application functions. The default port is 4141. Any files in the UI folder of the application will be exposed by a static file web server and accessible at http://localhost:4141, or whichever port you ran the web server at. You can read more in the UI Development article.

 

hcdev package

hcdev package -path some/path/to/myAppDir myApp.json

This command converts your source code to a package suitable for importing via hcadmin init --scaffold. You can specify a path to your source directory using the -path flag, and the output file.

If you don't specify an output file the package will be sent to the standard out, so if for example you are already in in your source directory you might do something like this:

hcdev package > ../myApp.json

which would save the package to the parent directory.

 

hcdev dump

hcdev dump --chain

Dumps the contents of the chain. This command only makes sense to use after you have run a stand-alone test, or after you have been doing manual tests using hcdev web.

You can Dump the chain to DOT format (to stdout).

  • DHT dump to dot not implemented in this PR (coming soon)
  • adds new --format argument (e.g. --format dot) that accepts previous formats as well.
  • existing --json flag still supported for backwards compatibility (can be deprecated later if desired)

Example usage:

Dump chain:

hcdev -execpath ~/.holochaindev -path clutter dump --chain --format dot > clutter.dot

Then view in a graphical DOT viewer:

xdot clutter.dot

Alternatively, you can dump the contents of the DHT.

hcdev dump --dht

 

Environment Variables

There are environment variables that you can set on the command line when you run one of the holochain commands, or put into files in the application or in your startup preferences.

Log/Printout settings
  • HCLOG_APP_ENABLE=0 -- TODO: Maybe this logs the application function calls
  • HCLOG_DHT_ENABLE=1 -- Enables logging of DHT communications which is really helpfult to understand what goes on between agents/nodes.
  • HCLOG_GOSSIP_ENABLE=true -- Enables additional DHT synchronization/gossip.
  • HCLOG_PREFIX="a prefix:" -- Primarily used in scenario 
  • HCLOG_DEBUG_ENABLE= <value?> -- Turns on/off printing output of debug commands.
Defaults
  • HC_DEFAULT_BOOTSTRAPSERVER= ??? -- Sets the address:[port] of a bootstrap server for finding peers using this app
  • HC_DEFAULT_ENABLEMDNS= ??? -- Turns on/off detection of local peers on you network.
  • HC_DEFAULT_ENABLENATUPNP= ??? -- Turns on/off the attempt to negotiate with the WiFi router to open a port for running your apps.

hcadmin

  • HOLOCHAINCONFIG_PORT=6283 -- Will be used as the `"Port"` in the `config.json` when you join an app using `hcadmin`. (e.g. $HOME/.holochain/YOURAPP/config.json)