Merge has a powerful command line client. It's designed to be used for both
user interaction and script integration. All commands that return data support
the --json flag which produces json output consumable by a script. Regular
text command output should not be used for scripting. We make absolutely zero
guarantees for the stability of plaintext output. Plaintext output also contains
shell control characters for color coding.
Many commands deal with elements that are part of a project, such as
experiments, realizations and materializations. In the absence of the
--project flag, the project in use is assumed to be the calling users personal
project. If a different project is desired, the --project flag may be used to
specify it.
All commands support prefix shortcuts. For example the command
mergetb show experiment phobos
can be expressed as
mergetb sh exp phobos
Only commands can be abbreviated, arguments to commands cannot.
The command line client uses the Merge OAuth2 system for authentication. Before
using the client, you must login using the login command.
The API used by the mergetb tool exposes a TLS endpoint only. For portals with
self signed certs, or development environments, the --cert flag may be used to
augment your systems CA pool with an additional CA chain from a PEM file.
The join command adds your account to a Merge portal. This is the first step to
getting going on any Merge portal. Your account will not be able to access the
API until an administrator activates it.
$ mergetb join -h
Join a Merge portal
Usage:
mergetb join[flags]
Flags:
-h, --help helpforjoin
Global Flags:
-c, --cert string TLS cert to use for connecting to portal
-p, --project string project to use (defaults to personal project)
The login command attempts to log a user into a Merge portal instance using an
OAuth2 authentication flow. Upon successful login two files are created
~/.merge/id: the username used to login
~/.merge/token: the token acquired from the authentication endpoint
The token is only good for a fixed period of time. How long depends on how the
policy of the particular portal. A typical token lifetime is around 24 hours.
$ mergetb login -h
Login to the Merge portal
Usage:
mergetb login <username>[flags]
Flags:
-h, --help helpfor login
Global Flags:
-c, --cert string TLS cert to use for connecting to portal
-p, --project string project to use (defaults to personal project)
Create a new experiment. This will create a new experiment under your personal
project, unless the --project flag is used to specify a different project.
The --desc flag may be used to provide an optional text description.
The --src flag may point to a topology written in Python using the Merge
Experimentation Library. When specified, the Merge CLI utility will attempt
to run the topology script, extract the corresponding XIR and use it as the
initial source version for the new experiment.
$ mergetb new experiment -h
Create a new experiment
Usage:
mergetb new experiment <name>[flags]
Flags:
-d, --desc string description
-h, --help helpfor experiment
-s, --src string source mx file
Global Flags:
-c, --cert string TLS cert to use for connecting to portal
-p, --project string project to use (defaults to personal project)
Push a new version of an experiment. The source.py argument is a Python3
topology script, written using the Merge Experimentation Library.
mergetb utility will attempt to run the Python script and extract XIR from the
topology. The extracted XIR is then pushed to the portal as the pushed version.
$ mergetb push -h
Push experiment version
Usage:
mergetb push <name><source.py>[flags]
Flags:
-h, --help helpfor push
Global Flags:
-c, --cert string TLS cert to use for connecting to portal
-p, --project string project to use (defaults to personal project)
Realize an experiment. Realization is the process of choosing and allocating
resources for an experiment.
When a realization is submitted, if sufficient
resources are available for the entire experiment, a pending allocation for all
the selected resources will be created. This pending allocation lasts 47
seconds. During this time window the realization may be explicitly
accepted or rejected by the user. No action within 47
seconds is an implicit reject. On rejection, all allocations are released. The --accept flag can be used to automatically accept a successful realization.
By default, the most recent experiment hash is used for realization. If an older
version is desired, the --version flag may be used to specify a specific
version hash.
$ mergetb realize -h
Realize an experiment
Usage:
mergetb realize <experiment><name>[flags]
Flags:
-a, --accept accept any successful realization
-h, --help helpfor realize
-v, --version string experiment source version
Global Flags:
-c, --cert string TLS cert to use for connecting to portal
-p, --project string project to use (defaults to personal project)
Accept transitions a realization in the pending state to the accepted state.
This means that the allocated resources will belong to the calling user until
explicitly freed.
$ mergetb accept -h
Accept a realization
Usage:
mergetb accept <experiment><name>[flags]
Flags:
-h, --help helpfor accept
Global Flags:
-c, --cert string TLS cert to use for connecting to portal
-p, --project string project to use (defaults to personal project)