Table of Contents

• Preface
• neuro
  • neuro job
    • neuro job run
    • neuro job submit
    • neuro job ls
    • neuro job status
    • neuro job exec
    • neuro job port-forward
    • neuro job logs
    • neuro job kill
    • neuro job top
    • neuro job browse
  • neuro storage
    • neuro storage cp
    • neuro storage ls
    • neuro storage rm
    • neuro storage mkdir
    • neuro storage mv
  • neuro image
    • neuro image ls
    • neuro image push
    • neuro image pull
  • neuro config
    • neuro config login
    • neuro config login-with-token
    • neuro config login-headless
    • neuro config show
    • neuro config show-token
    • neuro config docker
    • neuro config logout
  • neuro completion
    • neuro completion generate
    • neuro completion patch
  • neuro acl
    • neuro acl grant
    • neuro acl revoke
    • neuro acl list
  • neuro help
  • neuro run
  • neuro submit
  • neuro ps
  • neuro status
  • neuro exec
  • neuro port-forward
  • neuro logs
  • neuro kill
  • neuro top
  • neuro login
  • neuro logout
  • neuro cp
  • neuro ls
  • neuro rm
  • neuro mkdir
  • neuro mv
  • neuro images
  • neuro push
  • neuro pull
  • neuro share
• Api
• Contributing

Preface

Welcome to Neuromation API Python client. Package ship command line tool called neuro. With neuro you can:

• Execute and debug jobs
• Manipulate Data
• Make some fun

neuro

Usage:

neuro [OPTIONS] COMMAND [ARGS]...

Options:

Command Groups:

Commands:

neuro job

Job operations.

Usage:

neuro job [OPTIONS] COMMAND [ARGS]...

Options:

Commands:

neuro job run

Run an image with predefined configuration.

IMAGE container image name.

CMD list will be passed as commands to model container.

Usage:

neuro job run [OPTIONS] IMAGE [CMD]...

Examples:

# Starts a container pytorch:latest with two paths mounted.
# Directory storage://<USERNAME> is mounted as /var/storage/home in read-write mode,
# storage://neuromation is mounted as :/var/storage/neuromation as read-only.
neuro run pytorch:latest --volume=HOME

Options:

neuro job submit

Submit an image to run on the cluster.

IMAGE container image name.

CMD list will be passed as commands to model container.

Usage:

neuro job submit [OPTIONS] IMAGE [CMD]...

Examples:

# Starts a container pytorch:latest with two paths mounted. Directory /q1/
# is mounted in read only mode to /qm directory within container.
# Directory /mod mounted to /mod directory in read-write mode.
neuro submit --volume storage:/q1:/qm:ro --volume storage:/mod:/mod:rw pytorch:latest

Options:

neuro job ls

List all jobs.

Usage:

neuro job ls [OPTIONS]

Examples:

neuro ps --name my-experiments-v1 --status all
neuro ps --description=my favourite job
neuro ps -s failed -s succeeded -q

Options:

neuro job status

Display status of a job.

Usage:

neuro job status [OPTIONS] JOB

Options:

neuro job exec

Execute command in a running job.

Usage:

neuro job exec [OPTIONS] JOB CMD...

Options:

neuro job port-forward

Forward port(s) of a running job to local port(s).

Usage:

neuro job port-forward [OPTIONS] JOB LOCAL_REMOTE_PORT...

Examples:

# Forward local port 2080 to port 80 of job's container.
# You can use http://localhost:2080 in browser to access job's served http
neuro job port-forward my-fastai-job 2080:80

# Forward local port 2222 to job's port 22
# Then copy all data from container's folder '/data' to current folder
# (please run second command in other terminal)
neuro job port-forward my-job-with-ssh-server 2222:22
rsync -avxzhe ssh -p 2222 root@localhost:/data .

# Forward few ports at once
neuro job port-forward my-job- 2080:80 2222:22 2000:100

Options:

neuro job logs

Print the logs for a container.

Usage:

neuro job logs [OPTIONS] JOB

Options:

neuro job kill

Kill job(s).

Usage:

neuro job kill [OPTIONS] JOBS...

Options:

neuro job top

Display GPU/CPU/Memory usage.

Usage:

neuro job top [OPTIONS] JOB

Options:

neuro job browse

Opens a job's URL in a web browser.

Usage:

neuro job browse [OPTIONS] JOB

Options:

neuro storage

Storage operations.

Usage:

neuro storage [OPTIONS] COMMAND [ARGS]...

Options:

Commands:

neuro storage cp

Copy files and directories.

Either SOURCES or DESTINATION should have storage:// scheme. If scheme is
omitted, file:// scheme is assumed.

Use /dev/stdin and /dev/stdout file names to copy a file from terminal and
print the content of file on the storage to console.

Usage:

neuro storage cp [OPTIONS] [SOURCES]... [DESTINATION]

Examples:

# copy local file ./foo into remote storage root
neuro cp ./foo storage:///
neuro cp ./foo storage:/

# download remote file foo into local file foo with
# explicit file:// scheme set
neuro cp storage:///foo file:///foo

Options:

neuro storage ls

List directory contents.

By default PATH is equal user`s home dir (storage:)

Usage:

neuro storage ls [OPTIONS] [PATHS]...

Options:

neuro storage rm

Remove files or directories.

Usage:

neuro storage rm [OPTIONS] PATHS...

Examples:

neuro rm storage:///foo/bar
neuro rm storage:/foo/bar
neuro rm storage://{username}/foo/bar
neuro rm --recursive storage://{username}/foo/

Options:

neuro storage mkdir

Make directories.

Usage:

neuro storage mkdir [OPTIONS] PATHS...

Options:

neuro storage mv

Move or rename files and directories.

SOURCE must contain path to the file or directory existing on the storage,
and DESTINATION must contain the full path to the target file or directory.

Usage:

neuro storage mv [OPTIONS] SOURCES... DESTINATION

Examples:

# move or rename remote file
neuro mv storage://{username}/foo.txt storage://{username}/bar.txt
neuro mv storage://{username}/foo.txt storage://~/bar/baz/foo.txt

# move or rename remote directory
neuro mv storage://{username}/foo/ storage://{username}/bar/
neuro mv storage://{username}/foo/ storage://{username}/bar/baz/foo/

Options:

neuro image

Container image operations.

Usage:

neuro image [OPTIONS] COMMAND [ARGS]...

Options:

Commands:

neuro image ls

List images.

Usage:

neuro image ls [OPTIONS]

Options:

neuro image push

Push an image to platform registry.

Remote image must be URL with image:// scheme. Image names can contains tag.
If tags not specified 'latest' will be used as value.

Usage:

neuro image push [OPTIONS] IMAGE_NAME [REMOTE_IMAGE_NAME]

Examples:

neuro push myimage
neuro push alpine:latest image:my-alpine:production
neuro push alpine image://myfriend/alpine:shared

Options:

neuro image pull

Pull an image from platform registry.

Remote image name must be URL with image:// scheme. Image names can contain
tag.

Usage:

neuro image pull [OPTIONS] IMAGE_NAME [LOCAL_IMAGE_NAME]

Examples:

neuro pull image:myimage
neuro pull image://myfriend/alpine:shared
neuro pull image://username/my-alpine:production alpine:from-registry

Options:

neuro config

Client configuration.

Usage:

neuro config [OPTIONS] COMMAND [ARGS]...

Options:

Commands:

neuro config login

Log into Neuromation Platform.

URL is a platform entrypoint URL.

Usage:

neuro config login [OPTIONS] [URL]

Options:

neuro config login-with-token

Log into Neuromation Platform with token.

TOKEN is authentication token provided by Neuromation administration team.
URL is a platform entrypoint URL.

Usage:

neuro config login-with-token [OPTIONS] TOKEN [URL]

Options:

neuro config login-headless

Log into Neuromation Platform from non-GUI server environment.

URL is a platform entrypoint URL.

The command works similar to "neuro login" but instead of opening a browser
for performing OAuth registration prints an URL that should be open on guest
host.

Then user inputs a code displayed in a browser after successful login back
in neuro command to finish the login process.

Usage:

neuro config login-headless [OPTIONS] [URL]

Options:

neuro config show

Print current settings.

Usage:

neuro config show [OPTIONS]

Options:

neuro config show-token

Print current authorization token.

Usage:

neuro config show-token [OPTIONS]

Options:

neuro config docker

Configure docker client for working with platform registry

Usage:

neuro config docker [OPTIONS]

Options:

neuro config logout

Log out.

Usage:

neuro config logout [OPTIONS]

Options:

neuro completion

Output shell completion code.

Usage:

neuro completion [OPTIONS] COMMAND [ARGS]...

Options:

Commands:

neuro completion generate

Provide an instruction for shell completion generation.

Usage:

neuro completion generate [OPTIONS] [bash|zsh]

Options:

neuro completion patch

Automatically patch shell configuration profile to enable completion

Usage:

neuro completion patch [OPTIONS] [bash|zsh]

Options:

neuro acl

ACL operations.

Usage:

neuro acl [OPTIONS] COMMAND [ARGS]...

Options:

Commands:

neuro acl grant

Shares resource specified by URI to a USER with PERMISSION

Usage:

neuro acl grant [OPTIONS] URI USER [read|write|manage]

Examples:

neuro acl grant storage:///sample_data/ alice manage
neuro acl grant image:resnet50 bob read
neuro acl grant job:///my_job_id alice write

Options:

neuro acl revoke

Revoke from a USER permissions for previously shared resource specified by
URI

Usage:

neuro acl revoke [OPTIONS] URI USER

Examples:

neuro acl revoke storage:///sample_data/ alice
neuro acl revoke image:resnet50 bob
neuro acl revoke job:///my_job_id alice

Options:

neuro acl list

List resource available to a USER or shared by a USER

Usage:

neuro acl list [OPTIONS]

Examples:

neuro acl list
neuro acl list --scheme storage
neuro acl list --shared
neuro acl list --shared --scheme image

Options:

neuro help

Get help on a command.

Usage:

neuro help [OPTIONS] [COMMAND]...

Options:

neuro run

Run an image with predefined configuration.

IMAGE container image name.

CMD list will be passed as commands to model container.

Usage:

neuro run [OPTIONS] IMAGE [CMD]...

Examples:

# Starts a container pytorch:latest with two paths mounted.
# Directory storage://<USERNAME> is mounted as /var/storage/home in read-write mode,
# storage://neuromation is mounted as :/var/storage/neuromation as read-only.
neuro run pytorch:latest --volume=HOME

Options:

neuro submit

Submit an image to run on the cluster.

IMAGE container image name.

CMD list will be passed as commands to model container.

Usage:

neuro submit [OPTIONS] IMAGE [CMD]...

Examples:

# Starts a container pytorch:latest with two paths mounted. Directory /q1/
# is mounted in read only mode to /qm directory within container.
# Directory /mod mounted to /mod directory in read-write mode.
neuro submit --volume storage:/q1:/qm:ro --volume storage:/mod:/mod:rw pytorch:latest

Options:

neuro ps

List all jobs.

Usage:

neuro ps [OPTIONS]

Examples:

neuro ps --name my-experiments-v1 --status all
neuro ps --description=my favourite job
neuro ps -s failed -s succeeded -q

Options:

neuro status

Display status of a job.

Usage:

neuro status [OPTIONS] JOB

Options:

neuro exec

Execute command in a running job.

Usage:

neuro exec [OPTIONS] JOB CMD...

Options:

neuro port-forward

Forward port(s) of a running job to local port(s).

Usage:

neuro port-forward [OPTIONS] JOB LOCAL_REMOTE_PORT...

Examples:

# Forward local port 2080 to port 80 of job's container.
# You can use http://localhost:2080 in browser to access job's served http
neuro job port-forward my-fastai-job 2080:80

# Forward local port 2222 to job's port 22
# Then copy all data from container's folder '/data' to current folder
# (please run second command in other terminal)
neuro job port-forward my-job-with-ssh-server 2222:22
rsync -avxzhe ssh -p 2222 root@localhost:/data .

# Forward few ports at once
neuro job port-forward my-job- 2080:80 2222:22 2000:100

Options:

neuro logs

Print the logs for a container.

Usage:

neuro logs [OPTIONS] JOB

Options:

neuro kill

Kill job(s).

Usage:

neuro kill [OPTIONS] JOBS...

Options:

neuro top

Display GPU/CPU/Memory usage.

Usage:

neuro top [OPTIONS] JOB

Options:

neuro login

Log into Neuromation Platform.

URL is a platform entrypoint URL.

Usage:

neuro login [OPTIONS] [URL]

Options:

neuro logout

Log out.

Usage:

neuro logout [OPTIONS]

Options:

neuro cp

Copy files and directories.

Either SOURCES or DESTINATION should have storage:// scheme. If scheme is
omitted, file:// scheme is assumed.

Use /dev/stdin and /dev/stdout file names to copy a file from terminal and
print the content of file on the storage to console.

Usage:

neuro cp [OPTIONS] [SOURCES]... [DESTINATION]

Examples:

# copy local file ./foo into remote storage root
neuro cp ./foo storage:///
neuro cp ./foo storage:/

# download remote file foo into local file foo with
# explicit file:// scheme set
neuro cp storage:///foo file:///foo

Options:

neuro ls

List directory contents.

By default PATH is equal user`s home dir (storage:)

Usage:

neuro ls [OPTIONS] [PATHS]...

Options:

neuro rm

Remove files or directories.

Usage:

neuro rm [OPTIONS] PATHS...

Examples:

neuro rm storage:///foo/bar
neuro rm storage:/foo/bar
neuro rm storage://{username}/foo/bar
neuro rm --recursive storage://{username}/foo/

Options:

neuro mkdir

Make directories.

Usage:

neuro mkdir [OPTIONS] PATHS...

Options:

neuro mv

Move or rename files and directories.

SOURCE must contain path to the file or directory existing on the storage,
and DESTINATION must contain the full path to the target file or directory.

Usage:

neuro mv [OPTIONS] SOURCES... DESTINATION

Examples:

# move or rename remote file
neuro mv storage://{username}/foo.txt storage://{username}/bar.txt
neuro mv storage://{username}/foo.txt storage://~/bar/baz/foo.txt

# move or rename remote directory
neuro mv storage://{username}/foo/ storage://{username}/bar/
neuro mv storage://{username}/foo/ storage://{username}/bar/baz/foo/

Options:

neuro images

List images.

Usage:

neuro images [OPTIONS]

Options:

neuro push

Push an image to platform registry.

Remote image must be URL with image:// scheme. Image names can contains tag.
If tags not specified 'latest' will be used as value.

Usage:

neuro push [OPTIONS] IMAGE_NAME [REMOTE_IMAGE_NAME]

Examples:

neuro push myimage
neuro push alpine:latest image:my-alpine:production
neuro push alpine image://myfriend/alpine:shared

Options:

neuro pull

Pull an image from platform registry.

Remote image name must be URL with image:// scheme. Image names can contain
tag.

Usage:

neuro pull [OPTIONS] IMAGE_NAME [LOCAL_IMAGE_NAME]

Examples:

neuro pull image:myimage
neuro pull image://myfriend/alpine:shared
neuro pull image://username/my-alpine:production alpine:from-registry

Options:

neuro share

Shares resource specified by URI to a USER with PERMISSION

Usage:

neuro share [OPTIONS] URI USER [read|write|manage]

Examples:

neuro acl grant storage:///sample_data/ alice manage
neuro acl grant image:resnet50 bob read
neuro acl grant job:///my_job_id alice write

Options:

Api

TODO

Contributing

git clone https://github.com/neuromation/platform-api-clients.git
cd platform-api-clients/python

Before you begin, it is recommended to have clean virtual environment installed:

python -m venv .env
source .env/bin/activate

Development flow:

• Install dependencies: make init
• Run tests: make test
• Lint: make lint
• Publish to pypi: make publish