Merge pull request #415 from OpenFn/413-update-cli

update to cli docs given cli v1.0.0 release

Author: aleksa-krolls

docs/build-for-developers/cli-intro.md

@@ -12,8 +12,8 @@ simple to install, works on macOS, Windows, and Linux, and offers a range of
 functionality to enhance your developer experience with OpenFn. You can use the
 OpenFn CLI to:
 
-- Securely run OpenFn jobs and workflows
-- Troubleshoot and debug OpenFn jobs
+- Securely run OpenFn steps and workflows
+- Troubleshoot and debug OpenFn steps
 - Deployment of workflows to OpenFn
 
 ---
@@ -32,8 +32,8 @@ Before you begin with the @openfn/cli, make sure to follow these simple steps:
    [Install Node.js](https://kinsta.com/blog/how-to-install-node-js/) by
    following this guide.
 3. **Understand OpenFn Basics:** Have a basic understanding of OpenFn,
-   particularly jobs and adaptors. Check out the
-   [Intro section](/documentation) on this site.
+   particularly steps and adaptors. Check out the [Intro section](/documentation)
+   on this site.
 
 ---
 
@@ -58,20 +58,24 @@ command.
 
 <details><summary>Expand to see the expected output.</summary>
 
-    [CLI] ℹ Versions:
-            ▸ node.js     18.12.1
-            ▸ cli         0.4.11
-            ▸ runtime     0.2.2
-            ▸ compiler    0.0.38
-    [CLI] ℹ Running test job...
-    [CLI] ℹ Workflow object:
+    [CLI] ♦ Versions:
+         ▸ node.js     18.12.1
+         ▸ cli         1.0.0
+    [CLI] ℹ Running test workflow...
+
+    [CLI] ℹ Execution plan:
     [CLI] ℹ {
-        "start": "start",
-        "jobs": [
+    "options": {
+        "start": "start"
+    },
+    "workflow": {
+        "steps": [
         {
             "id": "start",
+            "state": {
             "data": {
-            "defaultAnswer": 42
+                "defaultAnswer": 42
+            }
             },
             "expression": "const fn = () => (state) => { console.log('Starting computer...'); return state; }; fn()",
             "next": {
@@ -91,19 +95,18 @@ command.
         }
         ]
     }
+    }
 
-    [CLI] ✔ Compilation complete
-    [R/T] ♦ Starting job start
+    [CLI] ✔ Compiled all expressions in workflow
+    [R/T] ℹ Executing undefined
+    [R/T] ℹ Starting step start
     [JOB] ℹ Starting computer...
-    [R/T] ℹ Operation 1 complete in 0ms
-    [R/T] ✔ Completed job start in 1ms
-    [R/T] ♦ Starting job calculate
+    [R/T] ✔ Completed step start in 1ms
+    [R/T] ℹ Starting step calculate
     [JOB] ℹ Calculating to life, the universe, and everything..
-    [R/T] ℹ Operation 1 complete in 0ms
-    [R/T] ✔ Completed job calculate in 1ms
-    [R/T] ♦ Starting job result
-    [R/T] ℹ Operation 1 complete in 0ms
-    [R/T] ✔ Completed job result in 0ms
+    [R/T] ✔ Completed step calculate in 1ms
+    [R/T] ℹ Starting step result
+    [R/T] ✔ Completed step result in 0ms
     [CLI] ✔ Result: 42
 
 </details>

docs/build-for-developers/cli-usage.md

@@ -6,8 +6,8 @@ slug: /cli-usage
 
 #### Execute a job, run a workflow, adjust logging, maintain adaptors, and save the state.
 
-You're probably here to run jobs (expressions) or workflows, which the CLI makes
-easy. Keep reading for an outline of the basic usage scenarios of the CLI.
+You're probably here to run steps (expressions) or workflows, which the CLI
+makes easy. Keep reading for an outline of the basic usage scenarios of the CLI.
 
 ---
 
@@ -17,25 +17,24 @@ To run a single job, you must explicitly specify which adaptor to use. You can
 find the list of publicly available [adaptors here](/adaptors). See examples
 below.
 
-> Pass the `-i` flag to auto-install that adaptor (it's safe to do this
-> redundantly).
+> Adaptors are auto-installed if the specified version is not detected.
 
 **Use a shorthand (e.g., `http`):**
 
 ```bash
-openfn path/to/job.js -ia http
+openfn path/to/job.js -a http
 ```
 
 **Use the full package name (e.g., `@openfn/language-http`):**
 
 ```bash
-openfn path/to/job.js -ia @openfn/language-http
+openfn path/to/job.js -a @openfn/language-http
 ```
 
 **Add a specific version:**
 
 ```bash
-openfn path/to/job.js -ia [email protected]
+openfn path/to/job.js -a [email protected]
 ```
 
 **Pass a path to a locally installed adaptor:**
@@ -54,15 +53,15 @@ it creates an `output.json` next to the job file.
 **You can specify custom paths for the output and state files:**
 
 ```bash
-openfn path/to/job.js -ia adaptor-name -o path/to/output.json -s path/to/state.json
+openfn path/to/job.js -a adaptor-name -o path/to/output.json -s path/to/state.json
 ```
 
 ### Return resulting state through stdout
 
 **Use `-O` to return the output through stdout:**
 
 ```bash
-openfn path/to/job.js -ia adaptor-name -O
+openfn path/to/job.js -a adaptor-name -O
 ```
 
 ---
@@ -98,7 +97,7 @@ export OPENFN_REPO_DIR=/path/to/repo
 **Auto-install adaptors and check if a matching version is found in the repo:**
 
 ```bash
-openfn path/to/job.js -ia adaptor-name
+openfn path/to/job.js -a adaptor-name
 ```
 
 **Remove all adaptors from the repo:**
@@ -116,25 +115,31 @@ openfn repo clean
 
 ```json
 {
-  "start": "a", // optionally specify the start node (defaults to jobs[0])
-  "jobs": [
-    {
-      "id": "a",
-      "expression": "fn((state) => state)", // code or a path
-      "adaptor": "@openfn/[email protected]", // specifiy the adaptor to use (version optional)
-      "data": {}, // optionally pre-populate the data object (this will be overriden by keys in in previous state)
-      "configuration": {}, // Use this to pass credentials
-      "next": {
-        // This object defines which jobs to call next
-        // All edges returning true will run
-        // If there are no next edges, the workflow will end
-        "b": true,
-        "c": {
-          "condition": "!state.error" // Note that this is an expression, not a function
+  "options": {
+    "start": "a" // optionally specify the start node (defaults to steps[0])
+  },
+  "workflows": {
+    "steps": [
+      {
+        "id": "a",
+        "expression": "fn((state) => state)", // code or a path
+        "adaptor": "@openfn/[email protected]", // specifiy the adaptor to use (version optional)
+        "state": {
+          "data": {} // optionally pre-populate the data object (this will be overriden by keys in in previous state)
+        },
+        "configuration": {}, // Use this to pass credentials
+        "next": {
+          // This object defines which steps to call next
+          // All edges returning true will run
+          // If there are no next edges, the workflow will end
+          "b": true,
+          "c": {
+            "condition": "!state.error" // Note that this is an expression, not a function
+          }
         }
       }
-    }
-  ]
+    ]
+  }
 }
 ```
 
@@ -143,7 +148,7 @@ openfn repo clean
 **To run a workflow:**
 
 ```bash
-openfn path/to/workflow.json -i
+openfn path/to/workflow.json -o tmp/output.json
 ```
 
 Check out this detailed [tutorial](cli-walkthrough#7-running-workflows) on