Improve CLI docs on running and re-running workflows locally

[mtuchi]

Description:

The current CLI documentation lacks detailed instructions on how to effectively run and re-run workflows locally. This enhancement will focus on providing clear guidance, especially on using specific options to control workflow execution.

Proposed Improvements:

1. Running Workflows Locally:

   • Add a section that explains how to run a workflow locally, emphasizing the use of the --cache-steps option to save all step results locally and avoid reprocessing. For example:

     openfn workflow.json -o tmp/output.json --cache-steps

2. Re-running Workflows:

   • Provide detailed instructions on how users can re-run workflows after making changes or upon failure, using the following options:
     • --start: Re-run from a specific start step. For example:

       openfn workflow.json -o tmp/output.json --start step2

     • --end: Re-run up to a specific end step. For example:

       openfn workflow.json -o tmp/output.json --end step3

     • --only: Re-run only a single specified step. For example:

       openfn workflow.json -o tmp/output.json --only step2

   • Emphasize that when re-running a workflow using --start, --end, or --only, the results will be loaded from the cache. Therefore, it's crucial to run the entire workflow first with --cache-steps enabled before using these options.

3. Best Practices:(Opt)

   • Suggest best practices for organizing workflows and managing local executions using the mentioned options.
   • Highlight common pitfalls and troubleshooting tips related to these options.

4. Using Help Command:(Opt)

   • Include instructions on how users can use openfn help to learn more about available commands and options within the OpenFn CLI.

Impact: This improvement will provide users with precise control over workflow execution, reducing errors and improving efficiency when running and re-running workflows locally.

Additional Notes: CLI Cache Steps Docs 👇🏽

• https://github.com/OpenFn/docs/pull/467

[josephjclark]

Regarding steps and cache-steps, is the problem that the information isn't there, or that it's not discoverable?

There is a section on running workflows, but it could use more examples and docs on steps I guess. It's maybe in the wrong place too.

The tutorial docs here might want a bit of an update too: https://docs.openfn.org/documentation/cli-walkthrough#7-running-workflows

[mtuchi]

Information is there but not discoverable