document new subcommands (#324)

content/docs/cml-with-dvc.md

@@ -46,19 +46,19 @@ jobs:
             -x actual \
             -y predicted \
             --show-vega master > vega.json
-          vl2png vega.json -s 1.5 > plot.png
-          cml publish --md plot.png >> report.md
+          vl2png vega.json -s 1.5 > plot-confusion.png
+          echo '![](./plot-confusion.png)' >> report.md
 
           # Publish regularization function diff
           echo "### Effects of regularization" >> report.md
           dvc plots diff \
             --target estimators.csv \
             -x Regularization \
             --show-vega master > vega.json
-          vl2png vega.json -s 1.5 > plot.png
-          cml publish --md plot.png >> report.md
+          vl2png vega.json -s 1.5 > plot-diff.png
+          echo '![](./plot-diff.png)' >> report.md
 
-          cml send-comment report.md
+          cml comment create --publish report.md
 ```
 
 See the [example repository](https://github.com/iterative/cml_dvc_case) for
@@ -127,7 +127,7 @@ Networking cost and transfer time can also be reduced using an appropriate
 <tab title="AWS">
 
 ```cli
-$ cml runner \
+$ cml runner launch \
   --cloud=aws \
   --cloud-region=us-west \
   --cloud-type=m+t4 \
@@ -139,7 +139,7 @@ $ cml runner \
 <tab title="GCP">
 
 ```cli
-$ cml runner \
+$ cml runner launch \
   --cloud=gcp \
   --cloud-region=us-west \
   --cloud-type=m+t4 \

content/docs/ref/send-github-check.md → content/docs/ref/check.md

@@ -1,10 +1,10 @@
-# Command Reference: `send-github-check`
+# Command Reference: `check`
 
 ```usage
-cml send-github-check [options] <markdown report file>
+cml check create [options] <markdown report file>
 ```
 
-Similar to [`send-comment`](/doc/ref/send-comment), but using GitHub's
+Similar to [`comment create`](/doc/ref/comment#create), but using GitHub's
 [checks interface](https://docs.github.com/en/rest/reference/checks).
 
 ## Options

content/docs/ref/send-comment.md → content/docs/ref/comment.md

@@ -1,22 +1,33 @@
-# Command Reference: `send-comment`
+# Command Reference: `comment`
+
+## create
+
+Post a Markdown report as a comment on a commit or pull/merge request.
 
 ```usage
-cml send-comment [options] <markdown report file>
+cml comment create [options] <markdown report file>
 ```
 
-Post a Markdown report as a comment on a commit or pull/merge request.
+## update
+
+Update the last CML comment instead of creating a new one. If no previous
+comment is found, create a new one.
+
+```usage
+cml comment update [options] <markdown report file>
+```
 
 <admon type="tip">
 
-If there's an associated pull/merge request, consider adding the `--pr` and
-`--update` flags.
+If there's an associated pull/merge request, consider using `update` with the
+`--pr` flag.
 
 </admon>
 
 <admon type="tip">
 
-If `cml pr` was used earlier in the workflow, use `--commit-sha=HEAD` to post
-comments to the new PR if desired.
+If [`cml pr`](/doc/ref/pr) was used earlier in the workflow, use
+`--commit-sha=HEAD` to post comments to the new PR if desired.
 
 </admon>
 
@@ -28,11 +39,15 @@ Any [generic option](/doc/ref) in addition to:
   [Git revision](https://git-scm.com/docs/gitrevisions) linked to this comment
   [default: `HEAD`].
 - `--pr`: Post to an existing PR/MR associated with the specified commit.
-- `--update`: Update the last CML comment (if any) instead of creating a new
-  one.
-- `--rm-watermark`: Don't inject a watermark into the comment. Will break some
-  CML functionality (such as `--update`) which needs to distinguish CML reports
-  from other comments.
+- `--watch`: Watch for changes and automatically update the comment (doesn't
+  exit, consider
+  [appending `&` to run in the background](<https://en.wikipedia.org/wiki/Job_control_(Unix)#Implementation>)).
+- `--publish`: Upload any local images found in the Markdown report.
+- `--publish-url=<url>`: Self-hosted image server URL [default:
+  `https://asset.cml.dev`], see
+  [minroud-s3](https://github.com/iterative/minroud-s3).
+- `--native`: Uses `--driver`'s native capabilities to `--publish` assets
+  instead of `--publish-url` (not available on `--driver=github`).
 
 ## FAQs and Known Issues
 
@@ -42,8 +57,8 @@ Any [generic option](/doc/ref) in addition to:
 
   This
   [error](https://github.community/t/comment-api-does-not-describe-commit-id-has-been-locked/159853/2)
-  is caused by using the default GitHub token with `cml send-comment --update`.
-  Use a
+  is caused by using the default GitHub token with
+  [`cml comment update`](#update). Use a
   [personal access token (PAT)](/doc/self-hosted-runners?tab=GitHub#personal-access-token)
   instead.
 

content/docs/ref/index.md

@@ -4,13 +4,13 @@
 
 All CML commands support the following options:
 
-- `--repo=<repo or org>`: Repository (or Organization) to be used [default:
+- `--repo=<repo or org>`: Repository (or Organization) URL or slug [default:
   *inferred from environment*].
 - `--token=<PAT>`:
   [Personal/project access token](https://cml.dev/doc/self-hosted-runners#personal-access-token)
   to be used [default: *inferred from environment*].
-- `--log={error,warn,info,debug}`: Maximum log level [default: `info`].
-- `--driver={github,gitlab,bitbucket}`: CI provider where the repository is
-  hosted [default: *inferred from environment*].
+- `--log={error,warn,info,debug}`: Logging verbosity [default: `info`].
+- `--driver={github,gitlab,bitbucket}`: CI provider where workflows are run
+  [default: *inferred from environment*].
 - `--help`: Show help.
 - `--version`: Show version number.

content/docs/ref/pr.md

@@ -1,11 +1,12 @@
 # Command Reference: `pr`
 
 ```usage
-cml pr [options] <pathspec>...
+cml pr create [options] <pathspec>...
 ```
 
 Commit specified files to a new branch and create a pull request. If sending a
-report afterwards, consider using `cml send-comment --pr --update`.
+report afterwards, consider using
+[`cml comment update --pr`](/doc/ref/comment#update).
 
 <admon type="info">
 
@@ -45,14 +46,14 @@ Any [generic option](/doc/ref) in addition to:
 ### Commit all files in current working directory
 
 ```cli
-$ cml pr .
+$ cml pr create .
 ```
 
 ### Automatically merge pull requests
 
 ```cli
 $ date > output.txt
-$ cml pr --auto-merge output.txt
+$ cml pr create --merge output.txt  # or --squash/--rebase
 ```
 
 The `--merge`, `--rebase`, and `--squash` options enable
@@ -65,7 +66,7 @@ checks isn't supported, `cml pr` will try to merge the pull request immediately.
 ## Command internals
 
 ```cli
-$ cml pr "**/*.py" "**/*.json"
+$ cml pr create "**/*.py" "**/*.json"
 ```
 
 is roughly equivalent to:

content/docs/ref/publish.md

@@ -4,7 +4,8 @@
 cml publish [options] <image file>
 ```
 
-Publicly host an image for displaying in a CML report.
+Publicly host an image for displaying in a CML report. Used internally by
+[`cml comment {create,update} --publish`](/doc/ref/comment).
 
 ## Options
 
@@ -17,8 +18,6 @@ Any [generic option](/doc/ref) in addition to:
   [default: *inferred from content*].
 - `--native`: Uses CI provider's native storage instead of CML's.
   [Not available on GitHub](https://github.com/iterative/cml/wiki/Backend-Supported-Features).
-- `--rm-watermark`: Don't inject a watermark into the comment. Will break some
-  CML functionality which needs to distinguish CML reports from other comments.
 - `--url=<...>`: Use a custom storage URL instead of asset.cml.dev. See
   [`minroud-s3`](https://github.com/iterative/minroud-s3) for a reference
   implementation.

content/docs/ref/runner.md

@@ -1,7 +1,7 @@
 # Command Reference: `runner`
 
 ```usage
-cml runner [options]
+cml runner launch [options]
 ```
 
 Starts a [runner](/doc/self-hosted-runners) (either via any supported cloud
@@ -99,7 +99,7 @@ An AWS ARN to an instance-profile:
 - `arn:aws:iam::1234567890:instance-profile/dvc-s3-access`
 
 ```cli
-$ cml runner \
+$ cml runner launch \
   --cloud-permission-set=arn:aws:iam::1234567890:instance-profile/dvc-s3-access \
   ...
 ```
@@ -114,7 +114,7 @@ A GCP service account email &
 - `my-sa@myproject.iam.gserviceaccount.com,scopes=storage-rw`
 
 ```cli
-$ cml runner \
+$ cml runner launch \
   --cloud-permission-set=my-sa@myproject.iam.gserviceaccount.com,scopes=storage-rw,datastore \
   ...
 ```
@@ -297,7 +297,7 @@ instance and exiting with an error.
 For example:
 
 ```cli
-$ cml runner \
+$ cml runner launch \
   --cloud-startup-script=IyEvYmluL2Jhc2gKCmVjaG8gImhlbGxvIHdvcmxkIgo= \
   ...
 ```
@@ -314,7 +314,7 @@ This can be used for debugging, for example allowing SSH access for a GitHub
 user:
 
 ```cli
-$ cml runner \
+$ cml runner launch \
   --cloud-startup-script=$(echo 'echo "$(curl https://github.com/${{ github.actor }}.keys)" >> /home/ubuntu/.ssh/authorized_keys' | base64 -w 0) \
   ...
 ```
@@ -358,7 +358,7 @@ Azure.
    `cml runner` command:
 
    ```cli
-   $ cml runner --cloud=... --cloud-ssh-private="$(cat key.pem)"
+   $ cml runner launch --cloud=... --cloud-ssh-private="$(cat key.pem)"
    ```
 
 3. Access the instance from your local system by using the generated key as an

content/docs/ref/tensorboard-dev.md → content/docs/ref/tensorboard.md

@@ -1,7 +1,7 @@
-# Command Reference: `tensorboard-dev`
+# Command Reference: `tensorboard`
 
 ```usage
-cml tensorboard-dev [options]
+cml tensorboard connect [options]
 ```
 
 Return a link to a <https://tensorboard.dev> page.
@@ -20,11 +20,9 @@ Any [generic option](/doc/ref) in addition to:
 - `--md`: Produce output in Markdown format (`[title](url)`).
 - `-t=<...>`, `--title=<...>`: Title for Markdown output [default: *value of
   `--name`*].
-- `--rm-watermark`: Don't inject a watermark into the comment. Will break some
-  CML functionality which needs to distinguish CML reports from other comments.
 
 ## Examples
 
 ```cli
-$ cml tensorboard-dev --logdir=./logs --title=Training --md >> report.md
+$ cml tensorboard connect --logdir=./logs --title=Training --md >> report.md
 ```

content/docs/ref/workflow.md

@@ -0,0 +1,19 @@
+# Command Reference: `workflow`
+
+```usage
+cml workflow rerun [options]
+```
+
+Rerun a workflow given a Job/Workflow ID.
+
+## Options
+
+Any [generic option](/doc/ref) in addition to:
+
+- `--id`: Job/Workflow ID.
+
+## Examples
+
+```cli
+$ cml workflow rerun --id=133742
+```