Skip to main content

Command Line Interface (CLI) executable

Repository Latest Release Latest Docker Release

The main Cogment module is a multi-platform standalone executable usable through a Command Line Interface, it is referred as the Cogment CLI.

The Cogment CLI includes the following services:

  • The Orchestrator, the heart of Cogment which executes the Trials by orchestrating the different user implemented services.
  • The Directory is the "directory" of services, where services register and can be found by clients and other services.
  • The Trial Datastore able to store and make available the data generated by the Trials.
  • The Model Registry which let's user store AI models and makes them available to actor implementations during training and in production.

Compatibility​

The Cogment CLI is available for the following OSes:

  • Linux with amd64 architecture (also known as x86_64), tested on Ubuntu 18.04 and 20.04, should be compatible with most recent distributions,
  • macOS with amd64 and arm64 (Apple Silicon) architectures, tested on macOS 12, should be compatible with any macOS version >= 10.15,
  • Windows with amd64 architecture, should be compatible with any Windows version >= Windows 10 version 1809.
tip

Starting with v2.2.0, the Cogment CLI is available for Linux, macOS and Windows on x86_64.

Starting with v2.6.0, the macOS arm64 version is also available.

Installation​

Installation script (compatible with linux and macOS)​

This installation method is compatible with virtually any Linux distribution, macOS and WSL2 on Windows. It only requires bash and curl.

First, download the install script and make sure you can run it using

curl --silent -L https://raw.githubusercontent.com/cogment/cogment/main/install.sh --output install-cogment.sh
chmod +x install-cogment.sh

You can then download and install the latest version to /usr/local/bin using

sudo ./install-cogment.sh

Other installation methods are available, for example:

  • Install version 2.2.0
    sudo ./install-cogment.sh --version 2.2.0
  • Install prereleased version 2.3.1-beta3, useful because prereleases are not considered by default
    sudo ./install-cogment.sh --version 2.2.0
  • Download the cogment exec in the current folder, make sure it is executable but skip the installation
    ./install-cogment.sh --skip-install
  • Specify manually the arch and os
    ./install-cogment.sh --arch amd64 --os Windows

All install options can be listed using

./install-cogment.sh --help

Uninstall is as simple as running:

sudo rm $(which cogment)
tip

Yes, it is possible to install Cogment as a one-line by piping the install script to bash ... at the risk of angering your system admin.

curl --silent -L https://raw.githubusercontent.com/cogment/cogment/main/install.sh | sudo ./install-cogment.sh

Manual installation​

If you are a Windows user (and also if you prefer to do a manual install), you can go through those instructions.

  1. Download the desired version from here for your platform.
  2. Copy it as cogment in a location that already belongs to your PATH (e.g. /usr/local/bin) or that you'll add to your PATH, and make sure it is executable (e.g. using chmod +x /usr/local/bin/cogment).

Docker​

A Cogment docker image is available on Docker Hub. It can be retrieved with the following:

docker pull cogment/cogment
note

The docker version of Cogment is very handy for server deployment, however, because of the nature of docker, users need to take care of port forwarding and volume mounting if needed.

Unsupported platform​

If your platform is not supported, add an issue including the details of your platform and do not hesitate to contact us.

Building from source​

Building from sources is perfectly possible. Please refer to the build instructions for more information.

Test your installation​

note

Depending on your platform and how you installed Cogment, it might be accessible as cogment, ./cogment, cogment.exe or docker run cogment/cogment. We will use cogment for the rest of this page and throughout the documentation.

With a working installation you can run the following in a terminal:

cogment version

You can then list all the commands by typing:

cogment help

or for help on each individual command:

cogment help <command>

Launching a Cogment app​

note

These instructions are only compatible with unix-like environments such as Linux, macOS and WSL2 on Windows.

In order to test that your installation is fully working, run an existing Cogment app, for example one of the steps of the tutorial.

Download or clone the sources for the official Rock-Paper-Scissors (RPS) tutorial from https://github.com/cogment/cogment-tutorial-rps.

To run this example you will need to have the following installed on top of Cogment:

Once it is done, run the following in the directory you retrieved:

cd 5-human-player
./run.sh build
./run.sh services_start

The first call to ./run.sh command will copy the cogment.yaml, and every referenced proto file, to each module directory, create virtualenvs, and install the python dependencies.

The second will start Cogment and the different services for this app. In another terminal you can connect to it and play a few games of RPS against a simple AI agent.

./run.sh client_start

Congratulations, you have a working installation of Cogment! We recommend you head to the Cogment tutorial to learn how to implement this RPS app from scratch.

Troubleshooting​

pipe creation failed (24): Too many open files error on macOS​

On macOS, it is possible that Cogment tries to open too many file handles. In this case, you'll get an error similar to pipe creation failed (24): Too many open files.

You can access the current limit and update it using ulimit -n. The default version should be something like 256, in most cases we found that Cogment requires 2048. You can set the limit with the following command:

$ ulimit -n 2048

This command changes the limit in the current shell session. This stackexchange question discusses different ways to make the change persist.

For debugging purposes, you can inspect the open file handles using lsof. E.g. lsof -c cogment | wc -l will count the number of open file handles by Cogment processes.

Last updated on