From c97c939013e432c827b5ee76cbfdeef8c2e6e659 Mon Sep 17 00:00:00 2001 From: clearml <> Date: Sun, 20 Apr 2025 15:55:05 +0300 Subject: [PATCH] Update readme with new commands --- README.md | 112 +++++++++++++++++++++++++----------------------------- 1 file changed, 52 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 0f0a1b3..763cc99 100644 --- a/README.md +++ b/README.md @@ -258,6 +258,15 @@ clearml-session --debugging-session Click on the JupyterLab/VSCode link, or drop directly into an SSH shell by typing `shell`. +### 👉 Remote session commands +While running inside the remote session, `clearml-session` adds the following commands to your shell: + +- `shutdown` - calling the `shutdown` command, as the name suggests, will shut down the interactive SSH session. + +- `clearml-sync-workspace` - calling this command will immediately upload your current workspace directory (see `--store-workspace` argument) to the ClearML configured storage (e.g. files server, S3 etc.). +Notice if this command does not exist this means the session does Not sync any local workspace. + + ## ❓ Frequently Asked Questions #### How does it work? @@ -306,21 +315,15 @@ clearml-session --help ```console clearml-session - CLI for launching JupyterLab / VSCode / SSH on a remote machine -usage: clearml-session [-h] [--version] [--attach [ATTACH]] [--shutdown [SHUTDOWN]] [--shell] - [--debugging-session DEBUGGING_SESSION] [--queue QUEUE] [--router-enabled] [--docker DOCKER] - [--docker-args DOCKER_ARGS] [--public-ip [true/false]] [--remote-ssh-port REMOTE_SSH_PORT] - [--vscode-server [true/false]] [--vscode-version VSCODE_VERSION] [--vscode-extensions VSCODE_EXTENSIONS] - [--jupyter-lab [true/false]] [--upload-files UPLOAD_FILES] [--continue-session CONTINUE_SESSION] - [--store-workspace STORE_WORKSPACE] [--git-credentials [true/false]] [--user-folder USER_FOLDER] - [--packages [PACKAGES [PACKAGES ...]]] [--requirements REQUIREMENTS] [--init-script [INIT_SCRIPT]] - [--config-file CONFIG_FILE] [--remote-gateway [REMOTE_GATEWAY]] [--base-task-id BASE_TASK_ID] - [--project PROJECT] [--session-name SESSION_NAME] [--session-tags [SESSION_TAGS [SESSION_TAGS ...]]] - [--disable-session-cleanup [true/false]] [--keepalive [true/false]] - [--queue-excluded-tag [QUEUE_EXCLUDED_TAG [QUEUE_EXCLUDED_TAG ...]]] - [--queue-include-tag [QUEUE_INCLUDE_TAG [QUEUE_INCLUDE_TAG ...]]] [--skip-docker-network [true/false]] - [--password PASSWORD] [--randomize [RANDOMIZE [RANDOMIZE ...]]] [--username USERNAME] - [--force-dropbear [true/false]] [--disable-store-defaults] [--disable-fingerprint-check] [--verbose] - [--yes] +usage: clearml-session [-h] [--version] [--attach [ATTACH]] [--shutdown [SHUTDOWN]] [--shell] [--debugging-session DEBUGGING_SESSION] [--queue QUEUE] [--router-enabled [true/false]] + [--docker DOCKER] [--docker-args DOCKER_ARGS] [--public-ip [true/false]] [--remote-ssh-port REMOTE_SSH_PORT] [--vscode-server [true/false]] + [--vscode-version VSCODE_VERSION] [--vscode-extensions VSCODE_EXTENSIONS] [--jupyter-lab [true/false]] [--upload-files UPLOAD_FILES] + [--continue-session CONTINUE_SESSION] [--store-workspace STORE_WORKSPACE] [--git-credentials [true/false]] [--user-folder USER_FOLDER] [--packages [PACKAGES ...]] + [--requirements REQUIREMENTS] [--init-script [INIT_SCRIPT]] [--config-file CONFIG_FILE] [--remote-gateway [REMOTE_GATEWAY]] [--base-task-id BASE_TASK_ID] + [--project PROJECT] [--session-name SESSION_NAME] [--session-tags [SESSION_TAGS ...]] [--disable-session-cleanup [true/false]] [--keepalive [true/false]] + [--queue-excluded-tag [QUEUE_EXCLUDED_TAG ...]] [--queue-include-tag [QUEUE_INCLUDE_TAG ...]] [--skip-docker-network [true/false]] [--password PASSWORD] + [--randomize [RANDOMIZE ...]] [--username USERNAME] [--force-dropbear [true/false]] [--disable-storage-packages [true/false]] [--disable-store-defaults] + [--disable-fingerprint-check] [--verbose] [--yes] {list,info,shutdown} ... clearml-session - CLI for launching JupyterLab / VSCode / SSH on a remote machine @@ -331,7 +334,7 @@ positional arguments: info Detailed information on specific session shutdown Shutdown specific session -optional arguments: +options: -h, --help show this help message and exit --version Display the clearml-session utility version --attach [ATTACH] Attach to running interactive session (default: previous session) @@ -339,87 +342,76 @@ optional arguments: Shut down an active session (default: previous session) --shell Open the SSH shell session directly, notice quiting the SSH session will Not shutdown the remote session --debugging-session DEBUGGING_SESSION - Pass existing Task id (experiment), create a copy of the experiment on a remote machine, and launch - jupyter/ssh for interactive access. Example --debugging-session + Pass existing Task id (experiment), create a copy of the experiment on a remote machine, and launch jupyter/ssh for interactive access. Example --debugging-session + --queue QUEUE Select the queue to launch the interactive session on (default: previously used queue) - --router-enabled If we have a clearml Router set, make sure we request direct TCP routing to our container. - --docker DOCKER Select the docker image to use in the interactive session on (default: previously used docker image or - `nvidia/cuda:11.6.2-runtime-ubuntu20.04`) + --router-enabled [true/false] + If we have a clearml Router set, make sure we request direct TCP routing to our container. + --docker DOCKER Select the docker image to use in the interactive session on (default: previously used docker image or `nvidia/cuda:11.6.2-runtime-ubuntu20.04`) --docker-args DOCKER_ARGS - Add additional arguments for the docker image to use in the interactive session on (default: previously - used docker-args) + Add additional arguments for the docker image to use in the interactive session on (default: previously used docker-args) --public-ip [true/false] - If True register the public IP of the remote machine. Set if running on the cloud. Default: false (use - for local / on-premises) + If True register the public IP of the remote machine. Set if running on the cloud. Default: false (use for local / on-premises) --remote-ssh-port REMOTE_SSH_PORT Set the remote ssh server port, running on the agent`s machine. (default: 10022) --vscode-server [true/false] Install vscode server (code-server) on interactive session (default: true) --vscode-version VSCODE_VERSION - Set vscode server (code-server) version, as well as vscode python extension version - (example: "3.7.4:2020.10.332292344") + Set vscode server (code-server) version, as well as vscode python extension version (example: "3.7.4:2020.10.332292344") --vscode-extensions VSCODE_EXTENSIONS - Install additional vscode extensions, as well as vscode python extension (example: "ms-python.python,ms- - python.black-formatter,ms-python.pylint,ms-python.flake8") + Install additional vscode extensions, as well as vscode python extension (example: "ms-python.python,ms-python.black-formatter,ms-python.pylint,ms-python.flake8") --jupyter-lab [true/false] Install Jupyter-Lab on interactive session (default: true) --upload-files UPLOAD_FILES - Advanced: Upload local files/folders to the remote session. Example: `/my/local/data/` will upload the - local folder and extract it into the container in ~/session-files/ + Advanced: Upload local files/folders to the remote session. Example: `/my/local/data/` will upload the local folder and extract it into the container in ~/session- + files/ --continue-session CONTINUE_SESSION Continue previous session (ID provided) restoring your workspace (see --store-workspace) --store-workspace STORE_WORKSPACE - Upload/Restore remote workspace folder. Example: `~/workspace/` will automatically restore/store the - *containers* folder and extract it into next the session. Use with --continue-session to continue your - previous work from your exact container state + Upload/Restore remote workspace folder. Example: `~/workspace/` will automatically restore/store the *containers* folder and extract it into next the session. Use + with --continue-session to continue your previous work from your exact container state --git-credentials [true/false] If true, local .git-credentials file is sent to the interactive session. (default: false) --user-folder USER_FOLDER Advanced: Set the remote base folder (default: ~/) - --packages [PACKAGES [PACKAGES ...]] - Additional packages to add, supports version numbers (default: previously added packages). examples: - --packages torch==1.7 tqdm + --packages [PACKAGES ...] + Additional packages to add, supports version numbers (default: previously added packages). examples: --packages torch==1.7 tqdm --requirements REQUIREMENTS - Specify requirements.txt file to install when setting the interactive session. Requirements file is read - and stored in `packages` section as default for the next sessions. Can be overridden by calling - `--packages` + Specify requirements.txt file to install when setting the interactive session. Requirements file is read and stored in `packages` section as default for the next + sessions. Can be overridden by calling `--packages` --init-script [INIT_SCRIPT] - Specify BASH init script file to be executed when setting the interactive session. Script content is - read and stored as default script for the next sessions. To clear the init-script do not pass a file + Specify BASH init script file to be executed when setting the interactive session. Script content is read and stored as default script for the next sessions. To + clear the init-script do not pass a file --config-file CONFIG_FILE - Advanced: Change the configuration file used to store the previous state (default: - ~/.clearml_session.json) + Advanced: Change the configuration file used to store the previous state (default: ~/.clearml_session.json) --remote-gateway [REMOTE_GATEWAY] - Advanced: Specify gateway ip/address:port to be passed to interactive session (for use with k8s - ingestion / ELB) + Advanced: Specify gateway ip/address:port to be passed to interactive session (for use with k8s ingestion / ELB) --base-task-id BASE_TASK_ID - Advanced: Set the base task ID for the interactive session. (default: previously used Task). Use `none` - for the default interactive session + Advanced: Set the base task ID for the interactive session. (default: previously used Task). Use `none` for the default interactive session --project PROJECT Advanced: Set the project name for the interactive session Task --session-name SESSION_NAME Advanced: Set the name of the interactive session Task - --session-tags [SESSION_TAGS [SESSION_TAGS ...]] + --session-tags [SESSION_TAGS ...] Advanced: Add tags to the interactive session for increased visibility --disable-session-cleanup [true/false] Advanced: If set, previous interactive sessions are not deleted --keepalive [true/false] - Advanced: If set, enables the transparent proxy always keeping the sockets alive. Default: False, do not - use transparent socket for mitigating connection drops. - --queue-excluded-tag [QUEUE_EXCLUDED_TAG [QUEUE_EXCLUDED_TAG ...]] + Advanced: If set, enables the transparent proxy always keeping the sockets alive. Default: False, do not use transparent socket for mitigating connection drops. + --queue-excluded-tag [QUEUE_EXCLUDED_TAG ...] Advanced: Excluded queues with this specific tag from the selection - --queue-include-tag [QUEUE_INCLUDE_TAG [QUEUE_INCLUDE_TAG ...]] + --queue-include-tag [QUEUE_INCLUDE_TAG ...] Advanced: Only include queues with this specific tag from the selection --skip-docker-network [true/false] - Advanced: If set, `--network host` is **not** passed to docker (assumes k8s network ingestion) (default: - false) - --password PASSWORD Advanced: Select ssh password for the interactive session (default: `randomly-generated` or previously - used one) - --randomize [RANDOMIZE [RANDOMIZE ...]] - Advanced: Recreate a new random ssh password for the interactive session options: `--randomize` one time - recreate random password, --randomize `always` create a new random password for every session + Advanced: If set, `--network host` is **not** passed to docker (assumes k8s network ingestion) (default: false) + --password PASSWORD Advanced: Select ssh password for the interactive session (default: `randomly-generated` or previously used one) + --randomize [RANDOMIZE ...] + Advanced: Recreate a new random ssh password for the interactive session options: `--randomize` one time recreate random password, --randomize `always` create a + new random password for every session --username USERNAME Advanced: Select ssh username for the interactive session (default: `root` or previously used one) --force-dropbear [true/false] Force using `dropbear` instead of SSHd + --disable-storage-packages [true/false] + If True automatic boto3/azure-storage-blob/google-cloud-storage python packages will not be added, you can manually add them using --packages --disable-store-defaults If set, do not store current setup as new default configuration --disable-fingerprint-check