From e585d09e98ceb2b2bdb2ddc694c73a7226d053b5 Mon Sep 17 00:00:00 2001
From: pollfly <75068813+pollfly@users.noreply.github.com>
Date: Wed, 1 Feb 2023 14:18:11 +0200
Subject: [PATCH] Add clearml-agent command descriptions (#463)

---
 docs/clearml_agent/clearml_agent_ref.md | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/docs/clearml_agent/clearml_agent_ref.md b/docs/clearml_agent/clearml_agent_ref.md
index 61d4b919..f5022402 100644
--- a/docs/clearml_agent/clearml_agent_ref.md
+++ b/docs/clearml_agent/clearml_agent_ref.md
@@ -12,7 +12,12 @@ The following page provides a reference to `clearml-agent`'s CLI commands:
 
 ## build
 
-Create a worker environment without executing the experiment.
+Use the `build` command to create worker environments without executing tasks. 
+
+You can build Docker containers according to the execution environments of specific tasks, which an agent can later
+use to execute other tasks. See tutorial [here](../guides/clearml_agent/exp_environment_containers.md).
+
+You can also create a Docker container that executes a specific task when launched. See tutorial [here](../guides/clearml_agent/executable_exp_containers.md). 
 
 ```bash
 clearml-agent build [-h] --id TASK_ID [--target TARGET]
@@ -31,7 +36,7 @@ clearml-agent build [-h] --id TASK_ID [--target TARGET]
 |---|----|---|
 |`--id`| Build a worker environment for this Task ID.|<img src="/docs/latest/icons/ico-optional-no.svg" alt="No" className="icon size-md center-md" />|
 |`--cpu-only`| Disable GPU access for the Docker container.|<img src="/docs/latest/icons/ico-optional-yes.svg" alt="Yes" className="icon size-md center-md" />|
-|`--docker`| Run agent in Docker mode. Specify Docker container that a worker will execute at launch. To specify the image name and optional arguments, use one of the following: <ul><li>`--docker <image_name> <args>` on the command line</li><li>`--docker` on the command line, and specify the default image name and arguments in the configuration file.</li></ul> Environment variable settings for Docker containers: <ul><li>`CLEARML_DOCKER_SKIP_GPUS_FLAG` - Ignore the `--gpus` flag inside the Docker container. This also allows you to execute ClearML Agent using Docker versions earlier than 19.03.</li><li>`NVIDIA_VISIBLE_DEVICES` - Limit GPU visibility for the Docker container.</li><li> `CLEARML_AGENT_GIT_USER` and `CLEARML_AGENT_GIT_PASS` - Pass these credentials to the Docker container at execution.</li></ul> To limit GPU visibility for Docker, set the `NVIDIA_VISIBLE_DEVICES` environment variable.| <img src="/docs/latest/icons/ico-optional-yes.svg" alt="Yes" className="icon size-md center-md" />|      
+|`--docker`| Run agent in Docker mode. Specify a Docker container that a worker will execute at launch. To specify the image name and optional arguments, use one of the following: <ul><li>`--docker <image_name> <args>` on the command line</li><li>`--docker` on the command line, and specify the default image name and arguments in the configuration file.</li></ul> Environment variable settings for Docker containers: <ul><li>`CLEARML_DOCKER_SKIP_GPUS_FLAG` - Ignore the `--gpus` flag inside the Docker container. This also allows you to execute ClearML Agent using Docker versions earlier than 19.03.</li><li>`NVIDIA_VISIBLE_DEVICES` - Limit GPU visibility for the Docker container.</li><li> `CLEARML_AGENT_GIT_USER` and `CLEARML_AGENT_GIT_PASS` - Pass these credentials to the Docker container at execution.</li></ul> To limit GPU visibility for Docker, set the `NVIDIA_VISIBLE_DEVICES` environment variable.| <img src="/docs/latest/icons/ico-optional-yes.svg" alt="Yes" className="icon size-md center-md" />|      
 |`--entry-point`| Used in conjunction with `--docker`, indicates how to run the Task specified by `--task-id` on Docker startup. The `--entry-point` options are: <ul><li>`reuse` - Overwrite the existing Task data.</li><li>`clone_task` - Clone the Task, and execute the cloned Task.</li></ul>|<img src="/docs/latest/icons/ico-optional-yes.svg" alt="Yes" className="icon size-md center-md" />|
 |`--force-docker`| Force using the agent-specified docker image (either explicitly in the `--docker` argument or using the agent's default docker image). If provided, the agent will not use any docker container information stored in the task itself (default `False`)|<img src="/docs/latest/icons/ico-optional-yes.svg" alt="Yes" className="icon size-md center-md" />|
 |`--git-pass`| Git password for repository access.|<img src="/docs/latest/icons/ico-optional-yes.svg" alt="Yes" className="icon size-md center-md" />|
@@ -53,7 +58,11 @@ clearml-agent config [-h]
 
 ## daemon 
 
-Run a worker, optionally in a Docker container, listening to a queue.
+Use the `daemon` command to spin up an agent on any machine: on-prem and/or cloud instance. When spinning up an agent, 
+assign it a queue(s) to service, and when experiments are added to its queues, the agent will pull and execute them. 
+
+With the `daemon` command you can configure your agent's behavior: allocate resources, prioritize queues, set it to run 
+in a Docker, and more. 
 
 ```bash
 clearml-agent daemon [-h] [--foreground] [--queue QUEUES [QUEUES ...]] [--order-fairness] 
@@ -99,7 +108,8 @@ clearml-agent daemon [-h] [--foreground] [--queue QUEUES [QUEUES ...]] [--order-
 
 ## execute
 
-Build and execute an experiment without a queue.
+Use the `execute` command to set an agent to build and execute specific tasks directly without listening to a queue.
+
 
 ```bash
 clearml-agent execute [-h] --id TASK_ID [--log-file LOG_FILE] [--disable-monitoring]