About

This repository contains the Command Line Client (CLI) for Clark which was produced by Elio.earth. We aim to simpify researcher's documentation and execution processes with Clark. The CLI is a tool which researchers use to document their workflows. This enables the researcher to definitively understand the end-to-end process of their research and creates a system of record with versioning for their research (similar to Github).

Pre-requisites

• Linux or MacOS
• Python 3.x
• MacOS only: sudo access to your machine (We use DTrace to trace system calls)

Install

The CLI is available from PyPI.

pip install clark-cli

Use

Below is a basic usage example from start to finish.

Register

Sign-up for an account at https://www.clarknest.com/register.

Remember to check your email to confirm your account. You will need to confirm your account before using the CLI.

Once you are registered, and you have confirmed your account you will be ready to issue commands with the CLI.

Create a Workflow

First login to the CLI using the credentials you registered with.

clark login

To view all the possible commands run:

clark --help

The next step is to create directories and workflows. Just like a filesystem, you can organize your workflows into directories. You initially start with an empty virtual filesystem.

Create a directory in the root folder (post login you always start in the root of your virtual filesystem)

clark add directory projectA

Change into the directory you just created.

clark cd projectA

Now you are ready to execute a script.

clark upload --message "A message to attach to this version of your workflow" python my_script.py

The CLI will run your script and auto-detect the inputs and outputs of the script. You will be asked to confirm the inputs and outputs before they are stored in the workflow. We upload the inputs, outputs and script to our servers.

If you made a mistake you can re-run the workflow and "replace" the previous run of the script.

clark upload --message "A different message for this run" --replace python my_script.py

Don't worry, you will have access to both versions of your workflow in the UI (described below). We create a version for each upload.

You can then go to another directory or workflow. You can back out of the workflow by:

clark cd ..

View a Workflow

You can then go to the Clark Nest to view your workflows, add notes to the nodes or workflows.

Examples

There some execution examples in the examples folder.

Contributing

If you have a bug-fix or small improvement we welcome pull requests. If unsure, please reach out to us at tech@elio.earth.

Setup Local Dev Environment

These instructions are intended for developers to set up their location development environment.

Install pyenv

Install Python 3.10.0

pyenv install 3.10.0

Download repo

cd ~/workspace/
git clone git@github.com:Elio-Earth/clark-cli.git

Create virtual env

pyenv virtualenv 3.10.0 clark-cli

Update pip

python -m pip install --upgrade pip

Install requirements

pip install -r requirements.txt

Install cli in development mode.

pip install --editable ~/workspace/clark-cli

Upgrade build

python -m pip install --upgrade build

Testing

To run the test suite

cd ~/workspace/clark-cli
pytest .