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
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.
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
The two root-level anchors correspond to the two circuit servers.
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 18.104.22.168:7711 /...
export CIRCUIT_DISCOVER=22.214.171.124: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
A more detailed explanation of their meaning and function can be found
in the documentation of the client package,