OpenFn / OpenFn/docs

Improve CLI docs on running and re-running workflows locally

Open
#537 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
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:

  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 👇🏽

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.