Expand description

A library and CLI to help create, run and interact with holochain conductor sandboxes. Warning this is still WIP and subject to change There’s probably a few bugs. If you find one please open an issue or make a PR.

CLI

The hc sandbox CLI makes it easy to run a dna that you are working on or someone has sent you. It has been designed to use sensible defaults but still give you the configurability when that’s required. Sandboxes are stored in tmp directories by default and the paths are persisted in a .hcXXX file which is created wherever you are using the CLI.

Install

Requirements
Building

From github:

cargo install holochain_cli --git https://github.com/holochain/holochain

From the holochain repo:

cargo install --path crates/hcYYY

Common usage

The best place to start is:

hc sandbox -h

This will be more up to date then this readme.

Run

This command can be used to generate and run conductor sandboxes.

hc sandbox run -h
hc sandbox r -h

In a folder with where your my-dna.dna is you can generate and run a new sandbox with:

hc sandbox r

If you have already created a sandbox previously then it will be reused (usually cleared on reboots).

Generate

Generates new conductor sandboxes and installs apps / dnas.

hc sandbox generate
hc sandbox g

For example this will generate 5 sandboxes with app ids set to my-app using the elemental-chat.dna from the current directory with a quic network sandbox to localhost. You don’t need to specify dnas when they are in the directory.

hc sandbox gen -a "my-app" -n 5 ./elemental-chat.dna network quic

You can also generate and run in the same command: (Notice the number of conductors and dna path must come before the gen sub-command).

hc sandbox r -n 5 ./elemental-chat.dna gen -a "my-app" network quic
Call

Allows calling the AdminRequest api. If the conductors are not already running they will be run to make the call.

hc sandbox call list-cells
List and Clean

These commands allow you to list the persisted sandboxes in the current directory (from the.hcXXX) file. You can use the index from:

hc sandbox list

Output:

hc-sandbox:
Sandboxes contained in `.hcXXX`
0: /tmp/KOXgKVLBVvoxe8iKD4iSS
1: /tmp/m8VHwwt93Uh-nF-vr6nf6
2: /tmp/t6adQomMLI5risj8K2Tsd

To then call or run an individual sandbox (or subset):

hc sandbox r -i=0,2

You can clean up these sandboxes with:

hc sandbox clean 0 2
hc sandbox clean

Library

This crate can also be used as a library so you can create more complex sandboxes / admin calls. See the docs:

cargo doc --open

and the examples.

Re-exports

pub use cli::HcSandbox;

Modules

Helpers for working with dna files.

Helpers for making AdminRequests to the admin api.

Definitions of StructOpt options for use in the CLI

Helpers for creating, reading and writing ConductorConfigs.

Helpers for generating new directories and ConductorConfig.

Helpers for running the conductor.

Common use sandboxes with lots of default choices.

Manage persistence of sandboxes

Macros

Expect that an enum matches a variant and return an error if it doesn’t.

Expect that an enum matches a variant and panic if it doesn’t.

Structs

An active connection to a running conductor.

Functions

Update the first admin interface to use this port.