Merge pull request #2652 from saucelabs/DEVX-2749-part4

docs: Add docs for saucectl imagerunner cli
saucelabs · Feb 21, 2024 · 5c090b6 · 5c090b6
2 parents 6e436f5 + c945a00
commit 5c090b6
Show file tree

Hide file tree

Showing 6 changed files with 313 additions and 15 deletions.
diff --git a/docs/dev/cli/saucectl/imagerunner/artifacts.md b/docs/dev/cli/saucectl/imagerunner/artifacts.md
@@ -0,0 +1,87 @@
+---
+id: artifacts-download
+title: saucectl imagerunner artifacts download
+sidebar_label: artifacts download
+---
+
+Get artifacts/files of the container from a Sauce Orchestrate run. Only the files specified in `artifacts` configuration are downloaded. Supports glob pattern.
+
+## Usage
+
+```bash
+$ saucectl imagerunner artifacts download <runID> <globPattern> [flags]
+```
+
+## Available Options
+
+<table id="table-cli">
+  <thead>
+    <tr>
+      <th width="30%">Flag</th>
+      <th width="10%">Shorthand</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><span className="t-cli"><a href="#--target-dir">--target-dir</a></span></td>
+      <td><span className="t-cli">None</span></td>
+      <td>Save files to target directory. Defaults to current working directory.</td>
+    </tr>
+    <tr>
+      <td><span className="t-cli"><a href="#--out">--out</a></span></td>
+      <td><span className="t-cli">-o</span></td>
+      <td>Output format to the console. Options: <code>text</code> (default) and <code>json</code>.</td>
+    </tr>
+    <tr>
+      <td><span className="t-cli"><a href="#--region">--region</a></span></td>
+      <td><span className="t-cli">-r</span></td>
+      <td>The Sauce Labs region. Options are <code>us-west-1</code> (default) and <code>eu-central-1</code>.</td>
+    </tr>
+  </tbody>
+</table>
+
+## Options Details
+
+### <span className="cli">--target-dir</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | STRING |</small></p>
+
+Save files to target directory. Defaults to current working directory.
+
+```bash
+saucectl imagerunner artifacts download <runID> <globPattern> --target-dir my-artifacts-dir
+```
+
+</div>
+
+### <span className="cli">--out</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | STRING |</small></p>
+
+Specifies the output format for the console. Options include: "text" or "json". The default setting is "text".
+
+**Shorthand:** `-o <text/json>`
+
+```bash
+saucectl imagerunner artifacts download <runID> <globPattern> --out json
+```
+
+</div>
+
+### <span className="cli">--region</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | STRING |</small></p>
+
+The Sauce Labs region. Options are `us-west-1` (default) and `eu-central-1`.
+
+**Shorthand:** `-r <region>`
+
+```bash
+saucectl imagerunner artifacts download <runID> <globPattern> --region us-west-1
+```
+
+</div>
diff --git a/docs/dev/cli/saucectl/imagerunner/list.md b/docs/dev/cli/saucectl/imagerunner/list.md
@@ -0,0 +1,69 @@
+---
+id: list
+title: saucectl imagerunner list
+sidebar_label: list
+---
+
+Returns the list of Sauce Orchestrate containers.
+
+## Usage
+
+```bash
+$ saucectl imagerunner list [flags]
+```
+
+## Available Options
+
+<table id="table-cli">
+  <thead>
+    <tr>
+      <th width="30%">Flag</th>
+      <th width="10%">Shorthand</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><span className="t-cli"><a href="#--out">--out</a></span></td>
+      <td><span className="t-cli">-o</span></td>
+      <td>Output format to the console. Options: <code>text</code> (default) and <code>json</code>.</td>
+    </tr>
+    <tr>
+      <td><span className="t-cli"><a href="#--region">--region</a></span></td>
+      <td><span className="t-cli">-r</span></td>
+      <td>The Sauce Labs region. Options are <code>us-west-1</code> (default) and <code>eu-central-1</code>.</td>
+    </tr>
+  </tbody>
+</table>
+
+## Options Details
+
+### <span className="cli">--out</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | STRING |</small></p>
+
+Specifies the output format for the console. Options include: "text" or "json". The default setting is "text".
+
+**Shorthand:** `-o <text/json>`
+
+```bash
+saucectl imagerunner list --out json
+```
+
+</div>
+
+### <span className="cli">--region</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | STRING |</small></p>
+
+The Sauce Labs region. Options are `us-west-1` (default) and `eu-central-1`.
+
+**Shorthand:** `-r <region>`
+
+```bash
+saucectl imagerunner list --region us-west-1
+```
+
+</div>
diff --git a/docs/dev/cli/saucectl/imagerunner/logs.md b/docs/dev/cli/saucectl/imagerunner/logs.md
@@ -0,0 +1,67 @@
+---
+id: logs
+title: saucectl imagerunner logs
+sidebar_label: logs
+---
+
+Fetches the logs from an imagerunner run.
+
+## Usage
+
+```bash
+$ saucectl imagerunner logs <runID> [flags]
+```
+
+## Available Options
+
+<table id="table-cli">
+  <thead>
+    <tr>
+      <th width="30%">Flag</th>
+      <th width="10%">Shorthand</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><span className="t-cli"><a href="#--live">--live</a></span></td>
+      <td><span className="t-cli">None</span></td>
+			<td>Tail the live log output from a running Sauce Orchestrate container. Defaults to `false`.</td>
+    </tr>
+    <tr>
+      <td><span className="t-cli"><a href="#--region">--region</a></span></td>
+      <td><span className="t-cli">-r</span></td>
+      <td>The Sauce Labs region. Options are <code>us-west-1</code> (default) and <code>eu-central-1</code>.</td>
+    </tr>
+  </tbody>
+</table>
+
+## Options Details
+
+### <span className="cli">--live</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | BOOLEAN |</small></p>
+
+Tail the live log output from a running Sauce Orchestrate container.
+
+```bash
+saucectl imagerunner logs <runID> --live
+```
+
+</div>
+
+### <span className="cli">--region</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | STRING |</small></p>
+
+The Sauce Labs region. Options are `us-west-1` (default) and `eu-central-1`.
+
+**Shorthand:** `-r <region>`
+
+```bash
+saucectl imagerunner logs <runID> --region us-west-1
+```
+
+</div>
diff --git a/docs/dev/cli/saucectl/imagerunner/stop.md b/docs/dev/cli/saucectl/imagerunner/stop.md
@@ -0,0 +1,49 @@
+---
+id: stop
+title: saucectl imagerunner stop
+sidebar_label: stop
+---
+
+Stops a running Sauce Orchestrate container.
+
+## Usage
+
+```bash
+$ saucectl imagerunner stop <runID> [flags]
+```
+
+## Available Options
+
+<table id="table-cli">
+  <thead>
+    <tr>
+      <th width="30%">Flag</th>
+      <th width="10%">Shorthand</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><span className="t-cli"><a href="#--region">--region</a></span></td>
+      <td><span className="t-cli">-r</span></td>
+      <td>The Sauce Labs region. Options are <code>us-west-1</code> (default) and <code>eu-central-1</code>.</td>
+    </tr>
+  </tbody>
+</table>
+
+## Options Details
+
+### <span className="cli">--region</span>
+
+<div className="cli-desc">
+<p><small>| OPTIONAL | STRING |</small></p>
+
+The Sauce Labs region. Options are `us-west-1` (default) and `eu-central-1`.
+
+**Shorthand:** `-r <region>`
+
+```bash
+saucectl imagerunner stop <runID> --region us-west-1
+```
+
+</div>
diff --git a/docs/orchestrate/saucectl-configuration.md b/docs/orchestrate/saucectl-configuration.md
@@ -460,18 +460,33 @@ The main command to run a Sauce Orchestrate job. Must be executed at the root le
 saucectl run
 ```
 
-### `saucectl imagerunner logs`
-
-Get logs of the container from a Sauce Orchestrate run.
-
-```bash
-saucectl imagerunner logs <runID>
-```
-
-### `saucectl imagerunner artifacts`
-
-Get artifacts/files of the container from a Sauce Orchestrate run. Only the files specified in `artifacts` configuration are downloaded.
-
-```bash
-saucectl imagerunner artifacts <runID>
-```
+### `saucectl imagerunner` Commands
+
+Supported commands:
+
+<table id="table-cli">
+  <thead>
+    <tr>
+      <th>Operation</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+   <tr>
+     <td><a href="/dev/cli/saucectl/imagerunner/artifacts-download">Get artifacts</a></td>
+     <td>Get artifacts/files of the container from a Sauce Orchestrate run.</td>
+   </tr>
+   <tr>
+     <td><a href="/dev/cli/saucectl/imagerunner/list">List containers</a></td>
+     <td>Return the list of Sauce Orchestrate containers.</td>
+   </tr>
+   <tr>
+     <td><a href="/dev/cli/saucectl/imagerunner/logs">Get logs</a></td>
+     <td>Fetch the logs from an imagerunner run.</td>
+   </tr>
+   <tr>
+     <td><a href="/dev/cli/saucectl/imagerunner/stop">Stop a container</a></td>
+     <td>Stop a running Sauce Orchestrate container.</td>
+   </tr>
+  </tbody>
+</table>
diff --git a/sidebars.js b/sidebars.js
@@ -789,6 +789,17 @@ module.exports = {
                                     collapsed: true,
                                     items: ['dev/cli/saucectl/docker/push'],
                                 },
+                                {
+                                    type: 'category',
+                                    label: 'saucectl imagerunner',
+                                    collapsed: true,
+                                    items: [
+                                        'dev/cli/saucectl/imagerunner/artifacts-download',
+                                        'dev/cli/saucectl/imagerunner/list',
+                                        'dev/cli/saucectl/imagerunner/logs',
+                                        'dev/cli/saucectl/imagerunner/stop',
+                                    ],
+                                },
                                 'dev/cli/saucectl/init',
                                 {
                                     type: 'category',