-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
81aad12
commit 66ff6b1
Showing
4 changed files
with
151 additions
and
136 deletions.
There are no files selected for viewing
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| --- | ||
| title: Intro to the OpenFn CLI | ||
| sidebar_label: Intro to CLI | ||
| slug: /cli | ||
| --- | ||
|
|
||
| :::info What is this tutorial? | ||
|
|
||
| - It's a _hands-on_ way to learn about the new OpenFn CLI. By following the | ||
| prompts and "challenges", a developer with a bit of Javascript experience | ||
| should be able to write, run, and debug complex, multi-step jobs with OpenFn, | ||
| using nothing but a text editor and their terminal. | ||
| - The estimated time to finish this developer challenge is 1 to 2 hours | ||
| (depending on your familiarity with the underlying concepts and tooling) | ||
| - If you are stuck and need help, please post in | ||
| [community.openfn.org](https://community.openfn.org/t/about-the-job-writing-category/11/1) | ||
|
|
||
| ::: | ||
|
|
||
| ## Intro to the OpenFn CLI | ||
|
|
||
| The [@openfn/cli](https://github.com/OpenFn/kit/tree/main/packages/cli) is a | ||
| command line interface for running OpenFn workflows locally. It enables | ||
| developers to run, build, and test steps in an OpenFn workflow. | ||
|
|
||
| This CLI replaces [@openfn/devtools](https://github.com/OpenFn/devtools) and | ||
| provides a new suite of features and improvements, including: | ||
|
|
||
| - a new runtime and compiler for executing and creating runnable OpenFn jobs, | ||
| - customizable logging output, | ||
| - automatic installation of language adaptors, | ||
| - and support for the adaptors monorepo | ||
| ([@openfn/adaptors](https://github.com/OpenFn/adaptors)) where all OpenFn | ||
| adaptor source code and documentation lives. | ||
|
|
||
| These features are designed to make it easier and more convenient for developers | ||
| to use and understand OpenFn. | ||
|
|
||
| :::caution Looking for a way to execute jobs from OpenFn v1 locally? Use Core! | ||
|
|
||
| If you're looking for a way to execute jobs running on the OpenFn v1 platform, | ||
| please see the documentation for **[@openfn/core](/documentation/core)** and | ||
| [Devtools](/documentation/devtools/home). | ||
|
|
||
| ::: | ||
|
|
||
|
|
||
| Learn more about CLI | ||
| [github.com/OpenFn/kit/](https://github.com/OpenFn/kit/tree/main/packages/cli) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,98 @@ | ||
| --- | ||
| title: The CLI | ||
| sidebar_label: CLI | ||
| slug: /cli | ||
| --- | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| 1. Ensure you have a code editor installed on your machine (e.g. | ||
| [VS Code](https://code.visualstudio.com/), | ||
| [Sublime](https://www.sublimetext.com/)) | ||
|
|
||
| 2. Install NodeJs **v18 is the minimum version required** | ||
|
|
||
| - To install a specific version of Node.js (in this case, version 18) on | ||
| Linux, Windows, or macOS, you can use a version manager such as nvm (Node | ||
| Version Manager) or any multiple runtime version manager eg: | ||
| [asdf](https://github.com/asdf-vm/asdf). These tools allow you to install | ||
| and switch between multiple versions of Node.js on the same machine. See | ||
| below for instructions for different operating systems. | ||
| - Read this article to learn how to install NodeJs in your machine | ||
| [kinsta.com/blog/how-to-install-node-js/](https://kinsta.com/blog/how-to-install-node-js/) | ||
|
|
||
| 3. Have a basic understanding of OpenFn—check out jobs and adaptors, at least, | ||
| in the [Intro section](documentation/next) of this site. | ||
| 4. Install the OpenFn CLI with `npm install -g @openfn/cli` | ||
|
|
||
| ## CLI Usage - Key Commands | ||
|
|
||
| You’ll learn about these commands in the following challenges, but please refer | ||
| to this section for the key commands used in working with the CLI. | ||
|
|
||
| ### Check the version | ||
|
|
||
| ```bash | ||
| openfn version | ||
| ``` | ||
|
|
||
| ### Get help | ||
|
|
||
| ```bash | ||
| openfn help | ||
| ``` | ||
|
|
||
| ### Run a job | ||
|
|
||
| ```bash | ||
| openfn path/to/job.js -ia {adaptor-name} | ||
| ``` | ||
|
|
||
| Note: You MUST specify which adaptor to use. Pass the `-i` flag to auto-install | ||
| that adaptor (it's safe to do this redundantly). | ||
|
|
||
| You can find the list of publicly available adaptors [here](/adaptors). | ||
|
|
||
| > Path is the job to load the job from (a .js file or a dir containing a job.js | ||
| > file) For example `openfn execute hello.js ` Reads hello.js, looks for state | ||
| > and output in foo | ||
| ```bash | ||
| -i, --autoinstall Auto-install the language adaptor | ||
| -a, --adaptors, --adaptor A language adaptor to use for the job | ||
| ``` | ||
|
|
||
| If an adaptor is already installed by auto install, you can use the command | ||
| without the `-i` options. i.e `openfn hello.js -a http` | ||
|
|
||
| ### Change log level | ||
|
|
||
| You can pass `-l info` or `--log info` to get more feedback about what's | ||
| happening, or `--log debug` for more details than you could ever use. Below is | ||
| the list of different log levels | ||
|
|
||
| ```bash | ||
| openfn hello.js -a http -l none | ||
| ``` | ||
|
|
||
| | log level | description | | ||
| | ------------ | -------------------------------------------------------- | | ||
| | `-l none` | Quiet mode | | ||
| | `-l default` | Top level information of what is happening | | ||
| | `-l info` | Get more feedback on what is happening openfn | | ||
| | `-l debug` | Get information about runtime, cli, compiler and the job | | ||
|
|
||
| ### Compilation | ||
|
|
||
| The CLI will attempt to compile your job code into normalized Javascript. It | ||
| will do a number of things to make your code robust, portable, and easier to | ||
| debug from a pure JS perspective. | ||
|
|
||
| ```bash | ||
| openfn compile [path] | ||
| ``` | ||
|
|
||
| Will compile the openfn job and print or save the resulting js. | ||
|
|
||
| Learn more about CLI | ||
| [github.com/OpenFn/kit/](https://github.com/OpenFn/kit/tree/main/packages/cli) |