Command Line Tools

Skip to Commands

hcadmin init

hcadmin join

hcadmin bridge

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 run two nodes on one device in developer mode

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 <caller-chain-name> <callee-chain-name> [--bridgeCallerAppData <data>] [--bridgeCalleeAppData <data>]

Bridging allows the caller chain to make calls to the callee 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 <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.

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 this behavior by specifying a different path in the HOLOPATHDEV environment variable or with the --execpath flag.

The --debug flag turns on low-level holochain debugging output during all commands. Note that when runing hcdev web any calls to debug() in your application code will be printed out to stdout regardless of this flag.

If you think that you are having networking difficulties, or want to configure your networking, check out the Networking page.

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.

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 to initialize the app
   --cloneExample="value" example from github.com/holochain to clone from
   --fromBranch value     specify branch to use with cloneExample
   --fromDevelop          specify that cloneExample should use the 'develop' branch

--package - Initialize from package: hcdev init

The --package flag lets you specify file produced by hcdev package or generated by the hc-scaffold to pre-populate your DNA.

--scaffold <path-to-package-file> <app-name>

--cloneExample - Clone from one of our example apps on github: hcdev init --cloneExample=<exampleName> <app-name>

The --cloneExample flag lets you specify the name of one of our example apps on github and will use git to download a copy of that app and will then clone it new UUID as a new app for your use.

--clone - Clone from existing app by path: hcdev init --clone <path-to-existing-app-dir> <app-name>

The --clone flag lets you specify a path to an existing app and will create a clone of that app with new UUID, and hence it will be a new app.

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:

settings



   {
        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:

settings



   {
        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

bs

Initializes a "bootstrap server". A bootstrap server can be used to help nodes find one another, connect, and start gossiping.

bs options

OPTIONS:
   --port                 set the port on which to run the bootstrap server

Example usage

$ bs --port 3143

Environment Variables

There are a number of Environment variables that can change the behavior of the command line utilites and the core Holochain code base:

Logging/Debugging

HCLOG_APP_ENABLE=1: Enables logging of application calls to debug(). This is enabled by default by hcdev but not enabled by hcd
HCLOG_DHT_ENABLE=1 -- Enables logging of DHT communications which is really helpful to understand what goes on between agents/nodes.
HCLOG_GOSSIP_ENABLE=1 -- Enables logging of gossip output.
HCLOG_DEBUG_ENABLE=1 -- Enables low-level holochain debugging output.
HCLOG_PREFIX="a prefix:" -- Adds a prefix to all log output. Primarily used internally by scenario and testing, so that you can tell which role the log entry comes from.
HCDEBUG=1 enables debugging output of the hcdev, hcadmin and hcd command line utilities (as distinc from the Holochain core codebase).

Gossip/World Model

HC_GOSSIP_INTERVAL=<seconds>: determines the gossip interval. Defaults to 2. To dissable gossip set this value to 0.
HC_HOLDING_INTERVAL=<seconds>: determines the world-model holding check interval. Set to 0 by default in Alpha 1.

Defaults

When you first run hcadmin init a number of system defaults for creating application config files are stored in ~/.holochain/system.conf These default values will be used later when hcadmin join creates the conf.json file for the app as it is added. The following environment variables override the default defaults. You can, of course, also manually edit the ~/.holochain/system.conf file after the fact if you want to change that.

HC_DEFAULT_BOOTSTRAPSERVER=bootstrap.holochain.net:10000 -- Sets the address:[port] of a bootstrap server for finding peers using this app
HC_DEFAULT_ENABLEMDNS=true -- Turns on/off detection of local peers on you network.
HC_DEFAULT_ENABLENATUPNP=true -- Turns on/off the attempt to negotiate with the WiFi router to open a port for running your apps.

If you want to override the defaults on a one-time basis as you run hcadmin join you can also set these environment variables:

HOLOCHAINCONFIG_DHTPORT
HOLOCHAINCONFIG_BOOTSTRAP
HOLOCHAINCONFIG_ENABLEMDNS
HOLOCHAINCONFIG_ENABLENATUPNP

Note that hcdev uses these values to implement its -DHTPport -bootstrapServer -mdns and -upnp flags, so use the flags when running hcdev, not these environment variables.