# Command line interface¶

SherlockML has a command line client, sml. This lets you:

• create, list, and terminate servers;
• access your servers via SSH;
• transfer large files using appropriate protocols like scp and rsync.

sml is designed to be used from a terminal on your local machine. It will work on macOS, Linux and Windows.

## Installation on MacOS and Linux¶

You can install it using pip:

$pip3 install -U sml  Once you have done this, continue to the Initializing sml section. ## Initializing sml¶ The first time you use sml, you will need to log in with a client ID and secret. This is different from your usual SherlockML username and password. To create client credentials, navigate to the Account page in SherlockML by clicking the icon showing your initial in the lower left of SherlockML, and click CLI credentials. Once you’ve created your credentials, run the following and enter the credentials when prompted: $ sml login


Once sml is configured, you can use it to create a new server on a project, sync data up to a project, and connect to a server from a terminal on your local machine.

To see the full list of commands run:

$sml --help  While most of the SherlockML functionality is accessible through the UI, there are some things that you can only do through the command line (for instance, bulk uploading code to your workspace). ## List projects and servers¶ You can list your SherlockML projects with: $ sml projects


and you can list a project’s running servers with:

$sml server list <project>  Note sml server list, like many other sml subcommands, takes a project as an argument. For projects with a unique name, you can simply give the project name, however for projects with non-unique names, you must pass the project ID. Project IDs are discoverable using sml projects -v. ## SSH into a server¶ Having successfully listed your servers, you can get SSH access using: $ sml shell <project> <server>


You can also provide sml shell with arbitrary extra arguments, which will be passed through to ssh. For example, to set up an SSH tunnel to an arbitrary network port on the server:

$sml shell <project> <server> -L 9000:localhost:8888  When you SSH into a server, you will be in the /home/sherlock directory. You probably want to access your project files first. These are located in /project. You can jump to that directory with: $ cd /project


Note

As with projects, sml shell and other commands that take a server as an argument can be passed either the server name or server ID. If you have servers with non-unique names, use sml server list <project> -v to discover their IDs for use in sml shell.

## Create a new server¶

You can create new servers for a project using:

$sml server new <options> <project>  For example: $ sml server new --cores=8 --memory=16 --name=new-server user-playground


Full options can be listed with sml server new --help.

Note

If the name of the project is not unique among projects you have access to, you must pass the project ID rather than the project name. Project IDs are discoverable using sml projects -v.

## Open the web interface of a server in your browser¶

You can open the web interface of a server in your browser with:

$sml server open <project>  sml will open the web interface of one of the running servers in the project. If you wish to open the interface of a specific server, pass the server’s name or ID with --server <server>. Note sml server open should be run from a terminal on your local machine, not from a SherlockML server. ## Copying files to and from your workspace¶ You can also use sml to upload and download files to and from your project on the command line. To upload a file, use sml file put: $ sml file put <project> <local-source> <remote-destination>


Note

sml file put should be run from a terminal on your local machine, not from a SherlockML server.

Similarly, to download a file, use sml file get:



$sml file sync-up <project> path/on/local/machine path/on/sherlockml --append --progress  Note sml file sync-up should be run from a terminal on your local machine, not from a SherlockML server. ## Uploading and downloading a large number of files to and from SherlockML¶ If you have an entire directory of files to upload to SherlockML, you can do so with sml file sync-up. To upload a directory: $ sml file sync-up <project> path/on/localmachine/ path/on/sherlockml


To download an entire directory from SherlockML to your local machine use sml file sync-down:

$sml file sync-down <project> path/on/sherlockml/ path/on/localmachine  You can also provide sml file sync-down and sml file sync-up with arbitrary extra arguments, which will be passed through to the rsync program. For example, to upload a directory with compression and delete files in the directory on SherlockML not present on your local machine, use: $ sml file sync-up <project> path/on/localmachine/ path/on/sherlockml --compress --delete


Note

Users unfamiliar with the rsync program, and especially the meaning of trailing slashes on the local and remote arguments, and the meaning of the --delete option, are strongly recommended to read its documentation before using sml file sync-down or sml file sync-up. Incorrect use of these features may result in data loss.

## Server environments¶

Server Environments can be created in SherlockML and applied through the web interface or through sml. The sml environment subcommands provide the ability to list and apply environments in a project, and to view the results of applying environments.

To list the environments in a project, run:

$sml environment list <project>  This will list all environments in the specified project. You can apply one of these environments to an existing server using the sml environment apply command: $ sml environment apply <project> <server> <environment>


As with other commands, each of the project, server and environment can be a name or an ID. To get the ID of server environments in a project, you can use the -v option with sml environment list.

The status of the last environment applied to a server can be checked with the sml environment status command:

$sml environment status <project> <server>  This will summarise the steps of the environment being applied, along with the overall status of the execution. To stream the logs of the environment application as it’s being applied, use the sml environment logs command: $ sml environment logs <project> <server>


You can also specify a particular step to stream the logs of using the --step command line option. This accepts the index of the step as given by sml environment status.

## Jobs¶

Jobs can be created in SherlockML and run through the web interface or through sml. The sml job subcommands provide the ability to list and run jobs in a project, and to view the logs for a run.

To list the jobs in a project, run:

$sml job list <project>  This will list all jobs in the specified project. You can run a job using the sml job run command: $ sml job run <project> <job>


The project and job can be a name or ID. To get the ID of job in a project, you can use the -v option with sml job list.

To run a job with parameters, run:

$sml job run <project> <job> "foo=bar,eggs=spam"  This will start a single job with the parameters “foo” and “eggs” set to “bar” and “spam” respectively. To run a job multiple times with different parameters, run: $ sml job run <project> <job> "foo=bar1,eggs=spam1" "foo=bar2,eggs=spam2"


This will start two jobs, the first with parameters “bar1” and “spam1” and the second with parameters “bar2” and “spam2”.

You can also run a job multiple times with no parameters using the --num-subruns command line option.

To list the runs of a job, use the sml job list-runs command:

$sml job list-runs <project> <job>  You can view the logs for a run using: $ sml job logs <project> <job> <run number>


For example, to view the logs for the second run of a job, use:

$sml job logs <project> <job> 2  To view the logs for the fifth sub-run of the third run of a job, use: $ sml job logs <project> <job> 3.5