diff --git a/docs/build-for-developers/for-devs.md b/docs/build-for-developers/build-compliant-apps.md similarity index 100% rename from docs/build-for-developers/for-devs.md rename to docs/build-for-developers/build-compliant-apps.md diff --git a/docs/build-for-developers/cli-intro.md b/docs/build-for-developers/cli-intro.md new file mode 100644 index 00000000000..c4ff1120aaa --- /dev/null +++ b/docs/build-for-developers/cli-intro.md @@ -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) diff --git a/docs/build-for-developers/cli.md b/docs/build-for-developers/cli-tutorial.md similarity index 85% rename from docs/build-for-developers/cli.md rename to docs/build-for-developers/cli-tutorial.md index db0a951c8e6..58e925fe8e6 100644 --- a/docs/build-for-developers/cli.md +++ b/docs/build-for-developers/cli-tutorial.md @@ -1,69 +1,9 @@ --- -title: The CLI -sidebar_label: CLI -slug: /cli +title: CLI Walkthrough & Challenges +sidebar_label: CLI Tutorial +slug: /cli-tutorial --- -:::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). - -::: - -## 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` ## Walkthrough & Challenges @@ -1107,76 +1047,4 @@ outlined below: } ``` -::: - -## 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) +::: \ No newline at end of file diff --git a/docs/build-for-developers/cli-usage.md b/docs/build-for-developers/cli-usage.md new file mode 100644 index 00000000000..d30acf8986e --- /dev/null +++ b/docs/build-for-developers/cli-usage.md @@ -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)