Improve CLI docs on running and re-running workflows locally
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 23
- Forks
- 20
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 6
Description
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:
-
Running Workflows Locally:
- Add a section that explains how to run a workflow locally, emphasizing the use of the
--cache-stepsoption to save all step results locally and avoid reprocessing. For example:openfn workflow.json -o tmp/output.json --cache-steps
- Add a section that explains how to run a workflow locally, emphasizing the use of the
-
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-stepsenabled before using these options.
- Provide detailed instructions on how users can re-run workflows after making changes or upon failure, using the following options:
-
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.
-
Using Help Command:(Opt)
- Include instructions on how users can use
openfn helpto learn more about available commands and options within the OpenFn CLI.
- Include instructions on how users can use
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 👇🏽
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the CLI documentation's run-a-job section and review the existing guidance alongside the documented --cache-steps, --start, --end, --only, and openfn help options. Done means the page explains initial caching, re-running selected workflow ranges or steps, and the relevant local-execution caveats with the examples from the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cli
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 50/100