Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

new-cli-install #939

Merged
merged 1 commit into from
Aug 9, 2024
Merged

new-cli-install #939

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 3 additions & 113 deletions docs/Researcher/cli-reference/new-cli/runai.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ authors:
date: 2024-Jun-18
---

The Run:ai Command-line Interface (CLI) tool for a Researcher to send deep learning workloads, acquire GPU-based containers, list jobs, and access other features in the Run:ai platform.

## The new Command-line interface

This command-line interface is a complete revamp of the command-line interface. Few highlights:
Expand All @@ -15,119 +17,7 @@ This command-line interface is a complete revamp of the command-line interface.
* The CLI is only available for Run:ai cluster version 2.18 and up.
* The new CLI is backward compatible with the older CLI.

## Summary

The Run:ai Command-line Interface (CLI) tool for a Researcher to send deep learning workloads, acquire GPU-based containers, list jobs, and access other features in the Run:ai platform.

```
runai [flags]
```

## Installing the Improved Command Line Interface

!!! Note
* Make sure the flag for the enhanced command line interface is enabled. To enable the Improved Command Line Interface Press the *Tools and Settings* icon, then *General*, then *Workloads*, then enable the *Improved Command Line Interface* toggle.
* Only clusters that are version 2.18 or later are supported.

To install the Improved Command Line Interface:

1. Press the *Help* icon, then select *Researcher Command Line Interface*.
2. From the dropdown, select a cluster.
3. Select your operating system.
4. Copy the installer command to your clipboard, then paste it into a terminal window and run the command.
5. Follow the instruction prompts during the installation process. Press `Enter` to use the default values (recommended).

### Install Command Auto-Completion

Auto-completion is installed automatically.

To install it manually:

* For *ZSH*, edit the file `~/.zshrc` and add the following lines:

```zsh
autoload -U compinit; compinit -i
source <(runai completion zsh)
```

* For *bash*, install the bash-completion package. Choose your operating system:

* Mac: `brew install bash-completion`
* Ubuntu/Debian: `sudo apt-get install bash-completion`
* Fedora/Centos: `sudo yum install bash-completion`

Then, edit the file `~/.bashrc` and add the following lines:

```bash
[[ -r “/usr/local/etc/profile.d/bash_completion.sh” ]] && . “/usr/local/etc/profile.d/bash_completion.sh”

source <(runai completion bash)
```

### Authenticating your CLI

After you have configured your shell, you will need to login to authenticate the CLI.
In your terminal widow run:

`runai login`

You will be redirected to your platform's login page.
Enter your user name and password and login.

You can then return to the terminal window to use the CLI.

### Set the default cluster

When you only have one cluster connected to the tenant, it will be set as default cluster when you first login.

When there are multiple clusters, you can select the cluster you want to set as default by running the following:

`runai cluster set --name <CLUSTER NAME>`

To find the desired cluster name run:

`runai cluster list`

### Set a default project

!!! Recommendation
Setting a default working project to, allows you to easily submit workloads without mentioning the project name in every command.

`runai project set --name=<project_name>`

If successful the following message will return:

`project <project name> configured successfully`

To see the current configuration run:

`runai config generate --json`

### Options

You can use the following configuration options with your CLI to customize your CLI.

```
--config-file string config file name; can be set by environment variable RUNAI_CLI_CONFIG_FILE (default "config.json")
--config-path string config path; can be set by environment variable RUNAI_CLI_CONFIG_PATH (default "~/.runai/")
-d, --debug enable debug mode
-h, --help help for runai
-v, --verbose enable verbose mode
```

### See Also

* [runai cluster](runai_cluster.md)&mdash;cluster management
* [runai config](runai_config.md)&mdash;configuration management
* [runai list](runai_list.md)&mdash;[Deprecated] display resource list. By default displays the job list
* [runai login](runai_login.md)&mdash;login to the control plane
* [runai logout](runai_logout.md)&mdash;logout from control plane
* [runai node](runai_node.md)&mdash;node management
* [runai nodepool](runai_nodepool.md)&mdash;node pool management
* [runai project](runai_project.md)&mdash;project management
* [runai report](runai_report.md)&mdash;report management
* [runai training](runai_training.md)&mdash;training management
* [runai upgrade](runai_upgrade.md)&mdash;upgrades the CLI to the latest version
* [runai version](runai_version.md)&mdash;print version information
* [runai workload](runai_workload.md)&mdash;workload management
* [runai workspace](runai_workspace.md)&mdash;workspace management
See installation instructions [here](../../../admin/researcher-setup/new-cli-install.md).
93 changes: 93 additions & 0 deletions docs/admin/researcher-setup/new-cli-install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Installing the New Command-line interface

This article explains the procedure for installing and configuring the __new__ researcher Command Line Interface (CLI).

!!! Important
This document refers to the new CLI which only works with clusters of version 2.18 and up.
The installation instructions for the older CLI are [here](cli-install.md).


## Enabling the new CLI

Under **Tools & Settings** → General settings → Workloads, enable the flag `Improved command line interface`

## Installing the CLI

1. Click the **Help (?)** icon in the top right corner
2. Select **Researcher Command Line Interface**
3. Select the **cluster** you want the CLI to communicate with
4. Select your computer’s **operating system**
5. Copy the installer command and run it in the terminal
6. Follow the installation process instructions
7. Click `Enter` to use the default values (recommended)

### Testing the installation

To verify the CLI client was installed properly

1. Open the terminal
2. Run the command `runai version`

## Configuring the CLI

Follow the steps below to configure the CLI.

### Authenticating the CLI

After installation, sign in to the Run:ai platform to authenticate the CLI:

1. Open the terminal on your local machine.
2. Run `runai login`.
3. Enter your username and password on the Run:ai platform's sign-in page.
4. Return to the terminal window to use the CLI.

### Setting the default cluster

If only one cluster is connected to the account, it is set as the default cluster when you first sign in.
If there are multiple clusters, you must follow the steps below to set your preferred cluster for workload submission:

1. Open the terminal on your local machine.
2. Run `runai cluster list` to find the required cluster name.
3. Run the following command `runai cluster set --name <CLUSTER NAME>`

### Setting a default project

Set a default working project, to easily submit workloads without mentioning the project name in every command.

1. Run the following command on the terminal:
`runai project set --name=<project_name>`
2. If successful, the following message is returned:
`project <project name> configured successfully`
3. To see the current configuration run:
`runai config generate --json`

### Installing command auto-completion

Auto-completion assists with completing the command syntax automatically for ease of use. Auto-completion is installed automatically.
The interfaces below require manual installation:

__Installation instructions for ZSH__

1. Edit the file `~/.zshrc`
2. Add the following code:

``` bash
autoload -U compinit; compinit -i
source <(runai completion zsh)
```

__Installation instructions for Bash__

1. Install the bash-completion package
2. Choose your operating system:
Mac: `brew install bash-completion`
Ubuntu/Debian: `sudo apt-get install bash-completion`
Fedora/Centos: `sudo yum install bash-completion`
3. Edit the file `~/.bashrc` and add the following lines:

``` bash
[[ -r “/usr/local/etc/profile.d/bash_completion.sh” ]] && . “/usr/local/etc/profile.d/bash_completion.sh”

source <(runai completion bash)
```

1 change: 1 addition & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,7 @@ nav:
- 'Researcher Setup' :
- 'Introduction' : 'admin/researcher-setup/researcher-setup-intro.md'
- 'Install the CLI' : 'admin/researcher-setup/cli-install.md'
- 'Install the New CLI' : 'admin/researcher-setup/new-cli-install.md'
- 'Configuration' :
- 'Overview' : 'admin/runai-setup/config/overview.md'
- 'Set Node Roles' : 'admin/runai-setup/config/node-roles.md'
Expand Down
Loading