Command-line Interface

The following is a list of the sub-commands contained in Surround’s CLI tool.

surround

The Surround Command Line Interface

usage: surround [-h] [-v]
                {init,run,lint,store,config,experimentation,split,viz,data}
                ...

Named Arguments

-v, --version

Show the current version of Surround Default: False

init

Initialize a new Surround project.

usage: surround init [-h] [-p PROJECT_NAME] [-d DESCRIPTION] [-w REQUIRE_WEB]
                     [path]

Positional Arguments

path	Path for creating a Surround project Default: “./”

Named Arguments

-p, --project-name
	Name of the project
-d, --description
	A description for the project
-w, --require-web
	Is web service required for the project

run

Run a Surround project assembler and task.

Without any arguments, all tasks will be listed.

Assemblers are defined in the __main__.py file of the current project. The default assembler that comes with every project is called baseline.

Tasks are defined in the dodo.py file of the current project. Each project comes with a set of default tasks listed below.

Containerised Tasks:

• build - Build a Docker image for your Surround project.
• dev - Run the specified assembler in a Docker container with the current source code (via drive mount, no build neccessary).
• prod - Build the Docker image and run the specified assembler inside a container (no drive mounting).
• batch - Run the specified assembler in a Docker container (mounting input and output folders) set to batch mode.
• train - Run the specified assembler in a Docker container (mounting input and output folders) set to train mode.
• web - Serve the specified assembler via HTTP endpoints inside a Docker container.
• remove - Remove the Docker image built for this project (if any).
• jupyter - Run a jupyter notebook server in a Docker container (mounting the whole project).

Local Tasks:

• batchLocal - Run the specified assembler locally set to batch-predict mode.
• trainLocal - Run the specified assembler locally set to train mode.
• webLocal - Serve the specified assembler via HTTP endpoints locally.

usage: surround run [-h] [task]

Positional Arguments

task	Task defined in dodo.py file of your project

lint

Run the Surround Linter on the current project.

For more information on what this does, see linter.

usage: surround lint [-h] [-l | path]

Positional Arguments

path	Path for running the Surround linter Default: ./

Named Arguments

-l, --list

List all Surround checkers Default: False

data

usage: surround data [-h] {create,inspect,lint} ...

subcommands

This tool must be called with one of the following commands

command

Possible choices: create, inspect, lint

Sub-commands:

create

Create a data container from a file or directory

surround data create [-h] (-f FILE | -d DIRECTORY | -m) [-o OUTPUT]
                     [-e EXPORT_METADATA]

Named Arguments

-f, --file	Path to file to import into container
-d, --directory
	Path to directory to import into container
-m, --metadata-only
	Generate metadata without a file system Default: False
-o, --output	Path to file to export container to (default: specified-path.data.zip)
-e, --export-metadata
	Path to JSON file to export metadata to

inspect

Inspect the metadata and/or contents of a data container

surround data inspect [-h] [-m | -c] container_file

Positional Arguments

container_file

Path to the data container to inspect

Named Arguments

-m, --metadata-only
	Inspect the metadata of the container only Default: False
-c, --content-only
	Inspect the contents of the container only Default: False

lint

Check the validity of a data container

surround data lint [-h] [-l] [-c CHECK_ID] container_path

Positional Arguments

container_path

Path to the container to perform checks on

Named Arguments

-l, --list	List the checks the linter will perform Default: False
-c, --check-id	Specify a single check to perform (get id from –list)

split

Tool to randomly split data into test, train, and validation sets.

Supports splitting:

• Directory of files
• CSV files
• Text files (just ensure you use the --no-header flag)

Example - Split a directory of images into train/test/validate:

$ surround split -d images -e png

Example - Reset a split directory:

$ surround spit --reset images

Example - Splitting and resetting a CSV file:

$ surround split -t test.csv
$ surround split --reset .

usage: surround split [-h] (-t TEXT_FILE | -d DIRECTORY | -r RESET)
                      [-e EXTENSION] [-tr TRAIN] [-te TEST] [-va VALIDATE]
                      [-nv] [-ns] [-nh]

Named Arguments

-t, --text-file
	Split text file into train/test/validate sets
-d, --directory
	Split directory into train/test/validate sets
-r, --reset	Path to directory containing train/test/validate folders to reset
-e, --extension
	File extension of the files to process (default: *) Default: “*”
-tr, --train	Percentage of files for training (default: 80%) Default: 80
-te, --test	Percentage of files for test (default: 10%) Default: 10
-va, --validate
	Percentage of files for validate (default: 10%) Default: 10
-nv, --no-validate
	Don’t produce a validation set when splitting Default: False
-ns, --no-shuffle
	Don’t randomise when splitting data Default: False
-nh, --no-header
	Use this flag when the text file has no headers Default: False