Using the command-line client

Once the circuit servers are started, you can create, observe and control circuit elements (i) interactively—using the circuit binary which doubles as a command-line client—as well as (ii) programmatically—using the circuit Go client package github.com/gocircuit/circuit/client. In fact, the circuit command-line tool is simply a front-end for the Go client library.

Clients (the tool or your own) dial into a circuit server in order to interact with the entire system. All servers are equal citizens in every respect and, in particular, any one can be used as a choice for dial-in.

Circuit client connected to a server.

The tool (described in more detail later) is essentially a set of commands that allow you to traverse the global hierarchical namespace of circuit elements, and interact with them, somewhat similarly to how one uses the Zookeeper namespace.

For example, to list the entire circuit cluster anchor hierarchy, type in

	circuit ls /

So, you might get something like this in response

	/X88550014d4c82e4d
	/X938fe923bcdef2390

The two root-level anchors correspond to the two circuit servers.

Circuit servers correspond to root-level anchors.

Pointing the tool to your circuit cluster

Before you can use the circuit tool, you need to tell it how to locate one circuit server for us a dial-in point.

There are two ways to provide the dial-in server address to the tool:

1. If the circuit servers were started with the -discover option or the CIRCUIT_DISCOVER environment variable, the command-line tool can use the same methods for finding a circuit server. E.g.

	circuit ls -discover 228.8.8.8:7711 /...

Or,

	export CIRCUIT_DISCOVER=228.8.8.8:7711
	circuit ls /...

2. With the command-line option -d, like e.g.

		circuit ls -d circuit://10.0.0.1:11022/78517/Q56e7a2a0d47a7b5d /

Or, equivalently, by setting the environment variable CIRCUIT to point to a file whose contents is the desired dial-in address. For example, (in bash):

		echo circuit://10.0.0.1:11022/78517/Q56e7a2a0d47a7b5d > ~/.circuit
		export CIRCUIT="~/.circuit"
		circuit ls /

A list of available tool commands is shown on the help screen

	circuit help

A more detailed explanation of their meaning and function can be found in the documentation of the client package, github.com/gocircuit/client.