@openfn/cli 0.0.41 → 0.2.0

package/README.md

@@ -1,17 +1,36 @@
 # @openfn/cli
 
-This package contains a new devtools CLI for running OpenFn jobs.
+This package contains a new devtools CLI for running and deploying OpenFn jobs.
 
 The CLI includes:
 
-* A secure runtime for executing OpenFn jobs and workflows
-* A compiler for making OpenFn jobs runnable
-* Configurable logging output
-* Auto-installation of language adaptors
-* Support for the adaptors monorepo
+- A secure runtime for executing OpenFn jobs and workflows
+- A compiler for making OpenFn jobs runnable
+- Configurable logging output
+- Auto-installation of language adaptors
+- Support for the adaptors monorepo
+- Deployment of workflows to OpenFn (and Lightning)
 
 ## Getting Started
 
+- [Installation](#installation)
+- [Updating](#updating)
+- [Migrating from devtools](#migrating-from-devtools)
+- [Basic Usage](#basic-usage)
+- [Advanced Usage](#advanced-usage)
+- [Deploying Workflows](#deploying-workflows)
+- [Logging](#logging)
+  - [Structured/JSON logging](#structuredjson-logging)
+- [Workflows](#workflows)
+- [Compilation](#compilation)
+- [Contributing](#contributing)
+  - [Usage from this repo](#usage-from-this-repo)
+  - [Installing globally](#installing-globally)
+  - [Repo Directory](#repo-directory)
+  - [Contribution changes](#contribution-changes)
+
+## Installation
+
 To install:
 
 ```
@@ -56,14 +75,13 @@ And then re-installing.
 
 If you're coming to the CLI from the old openfn devtools, here are a couple of key points to be aware of:
 
-* The CLI has a shorter, sleeker syntax, so your command should be much shorter
-* The CLI will automatically install adaptors for you (with full version control)
+- The CLI has a shorter, sleeker syntax, so your command should be much shorter
+- The CLI will automatically install adaptors for you (with full version control)
 
 ## Basic Usage
 
 You're probably here to run jobs (expressions) or workflows, which the CLI makes easy:
 
-
 ```
 openfn path/to/workflow.json
 openfn path/to/job.js -ia adaptor-name
@@ -87,24 +105,123 @@ You can pass `--log info` to get more feedback about what's happening, or `--log
 
 The CLI has a number of commands (the first argument after openfn)
 
-* execute - run a job
-* compile - compile a job to a .js file
-* docs - show documentation for an adaptor function
-* repo - manage the repo of installed modules
-* docgen - generate JSON documentation for an adaptor based on its typescript
+- execute - run a job
+- compile - compile a job to a .js file
+- docs - show documentation for an adaptor function
+- repo - manage the repo of installed modules
+- docgen - generate JSON documentation for an adaptor based on its typescript
 
 If no command is specified, execute will run.
 
 To get more information about a command, including usage examples, run `openfn <command> help`, ie, `openfn compile help`.
 
-## Logging 
+## Deploying Workflows
+
+> ⚠️ This feature is still in active development. Expect breaking changes.
+
+The CLI can deploy workflows to OpenFn.org and instances of Lightning.
+
+In order to deploy a workflow, you need the follow:
+
+- A project file written in YAML
+- A config file (or env vars) with your OpenFn credentials
+
+Example project file:
+
+```yaml
+---
+name: my-new-project
+workflows:
+  workflow-one:
+    name: My New Workflow
+    jobs:
+      job-a:
+        name: My First Job
+        enabled: true # default
+        adaptor: @openfn/language-http@latest
+        body: |
+          alterState(state => {
+            console.log("Hello world!");
+            return state;
+          });
+      job-b:
+        name: My Second Job
+        adaptor: @openfn/language-common@latest
+        body: |
+          alterState(state => {
+            console.log("Hello world!");
+            return state;
+          });
+    triggers:
+      trigger-one:
+        type: webhook # default
+    edges:
+      webhook->job-a:
+        source_trigger: trigger-one
+        target_job: job-a
+      job-a->job-b:
+        source_job: job-a
+        target_job: job-b
+
+```
+
+Example config file:
+
+```jsonc
+{
+  // Required, can be overridden or set with `OPENFN_API_KEY` env var
+  "apiKey": "***",
+
+  // Optional: can be set using the -p, defaults to project.yaml
+  "specPath": "project.yaml",
+
+  // Optional: can be set using -s, defaults to .state.json
+  "statePath": ".state.json",
+
+  // Optional: defaults to OpenFn.org's API, can be overridden or set with
+  // `OPENFN_ENDPOINT` env var
+  "endpoint": "https://app.openfn.org/api/provision"
+}
+```
+
+**Environment Variables**
+
+You can also set the following environment variables to avoid using a config file:
+
+- `OPENFN_API_KEY` - your OpenFn/Lightning API key
+- `OPENFN_ENDPOINT` - the endpoint to deploy to (defaults to OpenFn.org)
+
+**Using the CLI**
+
+```bash
+OPENFN_API_KEY="***" \
+openfn deploy
+
+# [CLI] ♦ Changes:
+#  {
+# + ... diff
+# - ... diff
+#  }
+#
+# ? Deploy? yes
+# [CLI] ♦ Deployed.
+```
+
+**Flags and Options**
+
+- `-p, --project-path <path>` - path to the project file (defaults to `project.yaml`)
+- `-s, --state-path <path>` - path to the state file (defaults to `.state.json`)
+- `-c, --config, --config-path` - path to the config file (defaults to `.config.json`)
+- `--no-confirm` - skip the confirmation prompt
+
+## Logging
 
 The CLI is actually a collection of packages, each of which will log with slightly different rules. To help understand where logs are coming from, each package prints a namespace or prefix at the start of its log.
 
-* [CLI] - the CLI itself, responsible for parsing and validating user input, reading and writing to disk, and executing the correct functionality.
-* [CMP] - the Compiler will parse openfn jobs into executable Javascript, changing your code
-* [R/T] - the Runtime executes your job code in a secure sandboxed environment, one operation at a time
-* [JOB] - the actual job code that your wrote. Any console.log statements in your job will appear under this namespace.
+- [CLI] - the CLI itself, responsible for parsing and validating user input, reading and writing to disk, and executing the correct functionality.
+- [CMP] - the Compiler will parse openfn jobs into executable Javascript, changing your code
+- [R/T] - the Runtime executes your job code in a secure sandboxed environment, one operation at a time
+- [JOB] - the actual job code that your wrote. Any console.log statements in your job will appear under this namespace.
 
 The CLI will log information at three different levels of verbosity: `default`, `info` and `debug` (`none` is also supported).
 
@@ -120,14 +237,18 @@ If something unexpected happens during a command, your first step should be to r
 
 `debug` level logging is highly verbose and aims to tell you everything that's going on under-the hood. This is aimed mostly at CLI/runtime developers and can be very useful for debugging problems.
 
-## Structred/JSON logging
+### Structred/JSON logging
 
 By default all logs will be printed as human-readable strings.
 
 For a more structured output, you can emit logs as JSON objects with `level`, `name` and `message` properties:
+
 ```
+
 { level: 'info', name: 'CLI', message: ['Loaded adaptor'] }
+
 ```
+
 Pass `--log-json` to the CLI to do this. You can also set the OPENFN_LOG_JSON env var (and use `--no-log-json` to disable).
 
 ## Workflows
@@ -141,37 +262,39 @@ To see an example workflow, run the test command with `openfn test`.
 A workflow has a structure like this (better documentation is coming soon):
 
 ```
+
 {
-  "start": "a", // optionally specify the start node (defaults to jobs[0])
-  "jobs": [
-    {
-      "id": "a",
-      "expression": "fn((state) => state)", // code or a path
-      "adaptor": "@openfn/language-common@1.75", // specifiy the adaptor to use (version optional)
-      "data": {}, // optionally pre-populate the data object (this will be overriden by keys in in previous state)
-      "configuration": {}, // Use this to pass credentials
-      "next": {
-        // This object defines which jobs to call next
-        // All edges returning true will run
-        // If there are no next edges, the workflow will end
-        "b": true,
-        "c": {
-          "condition": "!state.error" // Not that this is an expression, not a function
-        }
-      }
-    },
-  ]
+"start": "a", // optionally specify the start node (defaults to jobs[0])
+"jobs": [
+{
+"id": "a",
+"expression": "fn((state) => state)", // code or a path
+"adaptor": "@openfn/language-common@1.75", // specifiy the adaptor to use (version optional)
+"data": {}, // optionally pre-populate the data object (this will be overriden by keys in in previous state)
+"configuration": {}, // Use this to pass credentials
+"next": {
+// This object defines which jobs to call next
+// All edges returning true will run
+// If there are no next edges, the workflow will end
+"b": true,
+"c": {
+"condition": "!state.error" // Not that this is an expression, not a function
+}
+}
+},
+]
 }
+
 ```
 
 ## 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 and portable:
 
-* The language adaptor will be imported into the file
-* The adaptor's execute function will be exported form the file
-* All top level operations will be added to an array
-* That array will be made the default export of the file
+- The language adaptor will be imported into the file
+- The adaptor's execute function will be exported form the file
+- All top level operations will be added to an array
+- That array will be made the default export of the file
 
 The result of this is a lightweight, modern JS source file. It can be executed in any runtime environment: just execute each function in the exported array.
 
@@ -181,7 +304,7 @@ All jobs which work against `@openfn/core` will work in the new CLI and runtime
 
 If you want to see how the compiler is changing your job, run `openfn compile path/to/job -a <adaptor>` to return the compiled code to stdout. Add `-o path/to/output.js` to save the result to disk.
 
-# Contributing
+## Contributing
 
 First of all, thanks for helping! You're contributing to a digital public good that will always be free and open source and aimed at serving innovative NGOs, governments, and social impact organizations the world over! You rock. heart
 
@@ -189,44 +312,55 @@ To get this started, you'll want to clone this repo.
 
 You also need to install `pnpm`.
 
-## Usage from this repo
+### Usage from this repo
 
 You can run the cli straight from source with `pnpm`
 
 ```
+
 $ pnpm openfn path/to/job.js
 $ pnpm openfn -h
+
 ```
 
 See test/execute.test.ts for more usage examples
 
-## Installing globally
+### Installing globally
 
 To install the CLI globally from the build in repo:
 
 ```
+
 $ npm install -g .
+
 ```
 
 Note that this will install the built source from `dist`
 
-## Repo Directory
+### Repo Directory
 
 The CLI will save and load adaptors from an arbitrary folder on your system.
 
 You should set the OPENFN_REPO_DIR env var to something sensible.
 
 In `~/.bashrc` (or whatever you use), add:
+
 ```
+
 export OPENFN_REPO_DIR=~/repo/openfn/cli-repo
+
 ```
 
 To run adaptors straight from the adaptors monorepo:
 
 export OPENFN_ADAPTORS_REPO=~/repo/openfn/adaptors
 
-## Contributing changes
+### Contributing changes
 
 Open a PR at https://github.com/openfn/kit. Include a changeset and a description of your change.
 
-See the root readme for more details about changests,
+See the root readme for more details about changests,
+
+```
+
+```

package/dist/index.js

@@ -82,6 +82,34 @@ var compile = {
     setDefaultValue(opts2, "compile", true);
   }
 };
+var confirm = {
+  name: "no-confirm",
+  yargs: {
+    boolean: true,
+    description: "Skip confirmation prompts (e.g. 'Are you sure?')"
+  },
+  ensure: (opts2) => {
+    setDefaultValue(opts2, "confirm", true);
+  }
+};
+var configPath = {
+  name: "config",
+  yargs: {
+    alias: ["c", "config-path"],
+    description: "The location of your config file",
+    default: "./.config.json"
+  }
+};
+var describe = {
+  name: "describe",
+  yargs: {
+    boolean: true,
+    description: "Downloads the project yaml from the specified instance"
+  },
+  ensure: (opts2) => {
+    setDefaultValue(opts2, "describe", true);
+  }
+};
 var expandAdaptors = {
   name: "no-expand-adaptors",
   yargs: {
@@ -186,6 +214,14 @@ var outputPath = {
     delete opts2.o;
   }
 };
+var projectPath = {
+  name: "project-path",
+  yargs: {
+    string: true,
+    alias: ["p"],
+    description: "The location of your project.yaml file"
+  }
+};
 var repoDir = {
   name: "repo-dir",
   yargs: () => ({
@@ -240,6 +276,9 @@ var statePath = {
   yargs: {
     alias: ["s"],
     description: "Path to the state file"
+  },
+  ensure: (opts2) => {
+    delete opts2.s;
   }
 };
 var stateStdin = {
@@ -279,7 +318,12 @@ var expandYargs = (y2) => {
   }
   return y2;
 };
-var build = (opts2, yargs2) => opts2.reduce((_y, o) => yargs2.option(o.name, expandYargs(o.yargs)), yargs2);
+function build(opts2, yargs2) {
+  return opts2.reduce(
+    (_y, o) => yargs2.option(o.name, expandYargs(o.yargs)),
+    yargs2
+  );
+}
 var ensure = (command, opts2) => (yargs2) => {
   yargs2.command = command;
   opts2.filter((opt) => opt.ensure).forEach((opt) => {
@@ -296,63 +340,74 @@ var override = (command, yargs2) => {
   };
 };
 
-// src/repo/command.ts
-var repo = {
-  command: "repo [subcommand]",
-  desc: "Run commands on the module repo (install|clean)",
-  builder: (yargs2) => yargs2.command(clean).command(install).command(list).example("repo install -a http", "Install @openfn/language-http").example("repo clean", "Remove everything from the repo working dir")
-};
-var installOptions = [
-  repoDir,
-  override(expandAdaptors, {
-    default: true,
-    hidden: true
+// src/compile/command.ts
+var options = [
+  expandAdaptors,
+  adaptors,
+  ignoreImports,
+  inputPath,
+  logJson,
+  override(outputStdout, {
+    default: true
   }),
-  override(adaptors, {
-    description: "Specify which language-adaptor to install (allows short-form names to be used, eg, http)"
-  })
+  outputPath,
+  repoDir,
+  useAdaptorsMonorepo
 ];
-var install = {
-  command: "install [packages...]",
-  desc: "install one or more packages to the runtime repo. Use -a to pass shorthand adaptor names.",
-  handler: ensure("repo-install", installOptions),
-  builder: (yargs2) => build(installOptions, yargs2).example("install axios", "Install the axios npm package to the repo").example(
-    "install -a http",
-    "Install @openfn/language-http adaptor to the repo"
+var compileCommand = {
+  command: "compile [path]",
+  desc: "Compile an openfn job or workflow and print or save the resulting JavaScript.",
+  handler: ensure("compile", options),
+  builder: (yargs2) => build(options, yargs2).positional("path", {
+    describe: "The path to load the job or workflow from (a .js or .json file or a dir containing a job.js file)",
+    demandOption: true
+  }).example(
+    "compile foo/job.js",
+    "Compiles the job at foo/job.js and prints the result to stdout"
   ).example(
-    "install @openfn/language-http",
-    "Install the language-http adaptor to the repo"
+    "compile foo/workflow.json -o foo/workflow-compiled.json",
+    "Compiles the workflow at foo/work.json and prints the result to -o foo/workflow-compiled.json"
   )
 };
-var clean = {
-  command: "clean",
-  desc: "Removes all modules from the runtime module repo",
-  handler: ensure("repo-clean", [repoDir]),
-  builder: (yargs2) => build(
-    [
-      repoDir,
-      {
-        name: "force",
-        yargs: {
-          alias: ["f"],
-          description: "Skip the prompt and force deletion",
-          boolean: true
-        }
-      }
-    ],
-    yargs2
-  )
+var command_default = compileCommand;
+
+// src/deploy/command.ts
+var options2 = [statePath, projectPath, configPath, confirm, describe];
+var deployCommand = {
+  command: "deploy",
+  desc: "Deploy a project's config to a remote Lightning instance",
+  builder: (yargs2) => {
+    return build(options2, yargs2).example("deploy", "");
+  },
+  handler: ensure("deploy", options2)
 };
-var list = {
-  command: "list",
-  desc: "Show a report on what is installed in the repo",
-  aliases: ["$0"],
-  handler: ensure("repo-list", [repoDir]),
-  builder: (yargs2) => build([repoDir], yargs2)
+var command_default2 = deployCommand;
+
+// src/docgen/command.ts
+var docgenCommand = {
+  command: "docgen <specifier>",
+  desc: false,
+  handler: (argv) => {
+    argv.command = "docgen";
+  },
+  builder: (yargs2) => {
+    return yargs2.example("docgen @openfn/language-common@1.7.5", "");
+  }
+};
+var command_default3 = docgenCommand;
+
+// src/docs/command.ts
+var command_default4 = {
+  command: "docs <adaptor> [operation]",
+  desc: "Print help for an adaptor function. You can use short-hand for adaptor names (ie, common instead of @openfn/language-common)",
+  handler: (argv) => {
+    argv.command = "docs";
+  },
+  builder: (yargs2) => yargs2.example("docs common fn", "Print help for the common fn operation")
 };
 
 // src/execute/command.ts
-var options = [
+var options3 = [
   expandAdaptors,
   adaptors,
   autoinstall,
@@ -383,8 +438,8 @@ By default only state.data will be returned fron a job. Include --no-strict to w
   
 Remember to include the adaptor name with -a. Auto install adaptors with the -i flag.`,
   aliases: ["$0"],
-  handler: ensure("execute", options),
-  builder: (yargs2) => build(options, yargs2).positional("path", {
+  handler: ensure("execute", options3),
+  builder: (yargs2) => build(options3, yargs2).positional("path", {
     describe: "The path to load the job or workflow from (a .js or .json file or a dir containing a job.js file)",
     demandOption: true
   }).example(
@@ -401,70 +456,7 @@ Remember to include the adaptor name with -a. Auto install adaptors with the -i
     "Compile job.js with the http adaptor and print the code to stdout"
   )
 };
-var command_default = executeCommand;
-
-// src/compile/command.ts
-var options2 = [
-  expandAdaptors,
-  adaptors,
-  ignoreImports,
-  inputPath,
-  logJson,
-  override(outputStdout, {
-    default: true
-  }),
-  outputPath,
-  repoDir,
-  useAdaptorsMonorepo
-];
-var compileCommand = {
-  command: "compile [path]",
-  desc: "Compile an openfn job or workflow and print or save the resulting JavaScript.",
-  handler: ensure("compile", options2),
-  builder: (yargs2) => build(options2, yargs2).positional("path", {
-    describe: "The path to load the job or workflow from (a .js or .json file or a dir containing a job.js file)",
-    demandOption: true
-  }).example(
-    "compile foo/job.js",
-    "Compiles the job at foo/job.js and prints the result to stdout"
-  ).example(
-    "compile foo/workflow.json -o foo/workflow-compiled.json",
-    "Compiles the workflow at foo/work.json and prints the result to -o foo/workflow-compiled.json"
-  )
-};
-var command_default2 = compileCommand;
-
-// src/test/command.ts
-var options3 = [stateStdin];
-var command_default3 = {
-  command: "test",
-  desc: "Compiles and runs a test job, printing the result to stdout",
-  handler: ensure("test", options3),
-  builder: (yargs2) => build(options3, yargs2).example("test", "Run the test script")
-};
-
-// src/docgen/command.ts
-var docgenCommand = {
-  command: "docgen <specifier>",
-  desc: false,
-  handler: (argv) => {
-    argv.command = "docgen";
-  },
-  builder: (yargs2) => {
-    return yargs2.example("docgen @openfn/language-common@1.7.5", "");
-  }
-};
-var command_default4 = docgenCommand;
-
-// src/docs/command.ts
-var command_default5 = {
-  command: "docs <adaptor> [operation]",
-  desc: "Print help for an adaptor function. You can use short-hand for adaptor names (ie, common instead of @openfn/language-common)",
-  handler: (argv) => {
-    argv.command = "docs";
-  },
-  builder: (yargs2) => yargs2.example("docs common fn", "Print help for the common fn operation")
-};
+var command_default5 = executeCommand;
 
 // src/metadata/command.ts
 var options4 = [
@@ -487,9 +479,85 @@ var command_default6 = {
   )
 };
 
+// src/pull/command.ts
+var options5 = [statePath, projectPath, configPath];
+var pullCommand = {
+  command: "pull",
+  desc: "Pull aproject's state and spec from a Lightning Instance to the local directory",
+  builder: (yargs2) => {
+    return build(options5, yargs2).example("pull", "Pull an updated copy of a project spec and state from a Lightning Instance");
+  },
+  handler: ensure("pull", options5)
+};
+var command_default7 = pullCommand;
+
+// src/repo/command.ts
+var repo = {
+  command: "repo [subcommand]",
+  desc: "Run commands on the module repo (install|clean)",
+  builder: (yargs2) => yargs2.command(clean).command(install).command(list).example("repo install -a http", "Install @openfn/language-http").example("repo clean", "Remove everything from the repo working dir")
+};
+var installOptions = [
+  repoDir,
+  override(expandAdaptors, {
+    default: true,
+    hidden: true
+  }),
+  override(adaptors, {
+    description: "Specify which language-adaptor to install (allows short-form names to be used, eg, http)"
+  })
+];
+var install = {
+  command: "install [packages...]",
+  desc: "install one or more packages to the runtime repo. Use -a to pass shorthand adaptor names.",
+  handler: ensure("repo-install", installOptions),
+  builder: (yargs2) => build(installOptions, yargs2).example("install axios", "Install the axios npm package to the repo").example(
+    "install -a http",
+    "Install @openfn/language-http adaptor to the repo"
+  ).example(
+    "install @openfn/language-http",
+    "Install the language-http adaptor to the repo"
+  )
+};
+var clean = {
+  command: "clean",
+  desc: "Removes all modules from the runtime module repo",
+  handler: ensure("repo-clean", [repoDir]),
+  builder: (yargs2) => build(
+    [
+      repoDir,
+      {
+        name: "force",
+        yargs: {
+          alias: ["f"],
+          description: "Skip the prompt and force deletion",
+          boolean: true
+        }
+      }
+    ],
+    yargs2
+  )
+};
+var list = {
+  command: "list",
+  desc: "Show a report on what is installed in the repo",
+  aliases: ["$0"],
+  handler: ensure("repo-list", [repoDir]),
+  builder: (yargs2) => build([repoDir], yargs2)
+};
+
+// src/test/command.ts
+var options6 = [stateStdin];
+var command_default8 = {
+  command: "test",
+  desc: "Compiles and runs a test job, printing the result to stdout",
+  handler: ensure("test", options6),
+  builder: (yargs2) => build(options6, yargs2).example("test", "Run the test script")
+};
+
 // src/cli.ts
 var y = yargs(hideBin(process.argv));
-var cmd = y.command(command_default).command(command_default2).command(install).command(repo).command(command_default3).command(command_default5).command(command_default6).command(command_default4).option("log", {
+var cmd = y.command(command_default5).command(command_default).command(command_default2).command(install).command(repo).command(command_default8).command(command_default4).command(command_default6).command(command_default3).command(command_default7).option("log", {
   alias: ["l"],
   description: "Set the default log level to none, default, info or debug",
   array: true

package/dist/process/runner.js

@@ -78,13 +78,13 @@ var execute_default = async (input, state, opts, logger) => {
 };
 function parseAdaptors(opts) {
   const extractInfo = (specifier) => {
-    const [module, path7] = specifier.split("=");
+    const [module, path8] = specifier.split("=");
     const { name, version } = getNameAndVersion(module);
     const info = {
       name
     };
-    if (path7) {
-      info.path = path7;
+    if (path8) {
+      info.path = path8;
     }
     if (version) {
       info.version = version;
@@ -286,10 +286,10 @@ var stripVersionSpecifier = (specifier) => {
   return specifier;
 };
 var resolveSpecifierPath = async (pattern, repoDir, log) => {
-  const [specifier, path7] = pattern.split("=");
-  if (path7) {
-    log.debug(`Resolved ${specifier} to path: ${path7}`);
-    return path7;
+  const [specifier, path8] = pattern.split("=");
+  if (path8) {
+    log.debug(`Resolved ${specifier} to path: ${path8}`);
+    return path8;
   }
   const repoPath = await getModulePath(specifier, repoDir, log);
   if (repoPath) {
@@ -306,16 +306,16 @@ var loadTransformOptions = async (opts, log) => {
     const [pattern] = opts.adaptors;
     const [specifier] = pattern.split("=");
     log.debug(`Attempting to preload types for ${specifier}`);
-    const path7 = await resolveSpecifierPath(pattern, opts.repoDir, log);
-    if (path7) {
+    const path8 = await resolveSpecifierPath(pattern, opts.repoDir, log);
+    if (path8) {
       try {
         exports = await preloadAdaptorExports(
-          path7,
+          path8,
           opts.useAdaptorsMonorepo,
           log
         );
       } catch (e) {
-        log.error(`Failed to load adaptor typedefs from path ${path7}`);
+        log.error(`Failed to load adaptor typedefs from path ${path8}`);
         log.error(e);
       }
     }
@@ -652,7 +652,7 @@ var testHandler = async (options, logger) => {
     jobs: [
       {
         id: "start",
-        data: { defaultAnswer: 42 },
+        state: { data: { defaultAnswer: 42 } },
         expression: "const fn = () => (state) => { console.log('Starting computer...'); return state; }; fn()",
         next: {
           calculate: "!state.error"
@@ -684,12 +684,65 @@ var testHandler = async (options, logger) => {
   const silentLogger = createNullLogger();
   const state = await load_state_default(options, silentLogger);
   const code = await compile_default(options, logger);
-  const result = await execute_default(code, state, options);
+  const result = await execute_default(code, state, options, silentLogger);
   logger.success(`Result: ${result.data.answer}`);
   return result;
 };
 var handler_default3 = testHandler;
 
+// src/deploy/handler.ts
+import {
+  DeployError,
+  deploy,
+  getConfig,
+  validateConfig
+} from "@openfn/deploy";
+var actualDeploy = deploy;
+async function deployHandler(options, logger, deployFn = actualDeploy) {
+  try {
+    const config = mergeOverrides(await getConfig(options.configPath), options);
+    logger.debug("Deploying with config", JSON.stringify(config, null, 2));
+    if (options.confirm === false) {
+      config.requireConfirmation = options.confirm;
+    }
+    if (process.env["OPENFN_API_KEY"]) {
+      logger.info("Using OPENFN_API_KEY environment variable");
+      config.apiKey = process.env["OPENFN_API_KEY"];
+    }
+    if (process.env["OPENFN_ENDPOINT"]) {
+      logger.info("Using OPENFN_ENDPOINT environment variable");
+      config.endpoint = process.env["OPENFN_ENDPOINT"];
+    }
+    logger.debug("Deploying with config", config);
+    logger.info(`Deploying`);
+    validateConfig(config);
+    const isOk = await deployFn(config, logger);
+    process.exitCode = isOk ? 0 : 1;
+    return isOk;
+  } catch (error) {
+    if (error instanceof DeployError) {
+      logger.error(error.message);
+      process.exitCode = 10;
+      return false;
+    }
+    throw error;
+  }
+}
+function mergeOverrides(config, options) {
+  return {
+    ...config,
+    apiKey: pickFirst(process.env["OPENFN_API_KEY"], config.apiKey),
+    endpoint: pickFirst(process.env["OPENFN_ENDPOINT"], config.endpoint),
+    statePath: pickFirst(options.statePath, config.statePath),
+    configPath: options.configPath,
+    requireConfirmation: pickFirst(options.confirm, config.requireConfirmation)
+  };
+}
+function pickFirst(...args) {
+  return args.find((arg) => arg !== void 0 && arg !== null);
+}
+var handler_default4 = deployHandler;
+
 // src/docgen/handler.ts
 import { writeFile as writeFile3 } from "node:fs/promises";
 import { readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
@@ -701,20 +754,20 @@ var RETRY_COUNT = 20;
 var TIMEOUT_MS = 1e3 * 60;
 var actualDocGen = (specifier) => describePackage(specifier, {});
 var ensurePath = (filePath) => mkdirSync(path3.dirname(filePath), { recursive: true });
-var generatePlaceholder = (path7) => {
-  writeFileSync(path7, `{ "loading": true, "timestamp": ${Date.now()}}`);
+var generatePlaceholder = (path8) => {
+  writeFileSync(path8, `{ "loading": true, "timestamp": ${Date.now()}}`);
 };
 var finish = (logger, resultPath) => {
   logger.success("Done! Docs can be found at:\n");
   logger.print(`  ${path3.resolve(resultPath)}`);
 };
-var generateDocs = async (specifier, path7, docgen, logger) => {
+var generateDocs = async (specifier, path8, docgen, logger) => {
   const result = await docgen(specifier);
-  await writeFile3(path7, JSON.stringify(result, null, 2));
-  finish(logger, path7);
-  return path7;
+  await writeFile3(path8, JSON.stringify(result, null, 2));
+  finish(logger, path8);
+  return path8;
 };
-var waitForDocs = async (docs, path7, logger, retryDuration = RETRY_DURATION) => {
+var waitForDocs = async (docs, path8, logger, retryDuration = RETRY_DURATION) => {
   try {
     if (docs.hasOwnProperty("loading")) {
       logger.info("Docs are being loaded by another process. Waiting.");
@@ -726,19 +779,19 @@ var waitForDocs = async (docs, path7, logger, retryDuration = RETRY_DURATION) =>
             clearInterval(i);
             reject(new Error("Timed out waiting for docs to load"));
           }
-          const updated = JSON.parse(readFileSync(path7, "utf8"));
+          const updated = JSON.parse(readFileSync(path8, "utf8"));
           if (!updated.hasOwnProperty("loading")) {
             logger.info("Docs found!");
             clearInterval(i);
-            resolve(path7);
+            resolve(path8);
           }
           count++;
         }, retryDuration);
       });
     } else {
-      logger.info(`Docs already written to cache at ${path7}`);
-      finish(logger, path7);
-      return path7;
+      logger.info(`Docs already written to cache at ${path8}`);
+      finish(logger, path8);
+      return path8;
     }
   } catch (e) {
     logger.error("Existing doc JSON corrupt. Aborting");
@@ -755,35 +808,35 @@ var docgenHandler = (options, logger, docgen = actualDocGen, retryDuration = RET
     process.exit(9);
   }
   logger.success(`Generating docs for ${specifier}`);
-  const path7 = `${repoDir}/docs/${specifier}.json`;
-  ensurePath(path7);
+  const path8 = `${repoDir}/docs/${specifier}.json`;
+  ensurePath(path8);
   const handleError = () => {
     logger.info("Removing placeholder");
-    rmSync(path7);
+    rmSync(path8);
   };
   try {
-    const existing = readFileSync(path7, "utf8");
+    const existing = readFileSync(path8, "utf8");
     const json = JSON.parse(existing);
     if (json && json.timeout && Date.now() - json.timeout >= TIMEOUT_MS) {
       logger.info(`Expired placeholder found. Removing.`);
-      rmSync(path7);
+      rmSync(path8);
       throw new Error("TIMEOUT");
     }
-    return waitForDocs(json, path7, logger, retryDuration);
+    return waitForDocs(json, path8, logger, retryDuration);
   } catch (e) {
     if (e.message !== "TIMEOUT") {
-      logger.info(`Docs JSON not found at ${path7}`);
+      logger.info(`Docs JSON not found at ${path8}`);
     }
     logger.debug("Generating placeholder");
-    generatePlaceholder(path7);
-    return generateDocs(specifier, path7, docgen, logger).catch((e2) => {
+    generatePlaceholder(path8);
+    return generateDocs(specifier, path8, docgen, logger).catch((e2) => {
       logger.error("Error generating documentation");
       logger.error(e2);
       handleError();
     });
   }
 };
-var handler_default4 = docgenHandler;
+var handler_default5 = docgenHandler;
 
 // src/docs/handler.ts
 import { readFile as readFile2 } from "node:fs/promises";
@@ -825,7 +878,7 @@ var docsHandler = async (options, logger) => {
     logger.success(`Showing docs for ${adaptorName} v${version}`);
   }
   logger.info("Generating/loading documentation...");
-  const path7 = await handler_default4(
+  const path8 = await handler_default5(
     {
       specifier: `${name}@${version}`,
       repoDir
@@ -833,8 +886,8 @@ var docsHandler = async (options, logger) => {
     createNullLogger()
   );
   let didError = false;
-  if (path7) {
-    const source = await readFile2(path7, "utf8");
+  if (path8) {
+    const source = await readFile2(path8, "utf8");
     const data = JSON.parse(source);
     let desc;
     if (operation) {
@@ -861,7 +914,7 @@ var docsHandler = async (options, logger) => {
     logger.error("Not found");
   }
 };
-var handler_default5 = docsHandler;
+var handler_default6 = docsHandler;
 
 // src/metadata/cache.ts
 import { createHash } from "node:crypto";
@@ -978,10 +1031,49 @@ var metadataHandler = async (options, logger) => {
     process.exit(1);
   }
 };
-var handler_default6 = metadataHandler;
+var handler_default7 = metadataHandler;
+
+// src/pull/handler.ts
+import path5 from "path";
+import fs3 from "node:fs/promises";
+import {
+  getProject,
+  getConfig as getConfig2,
+  getState
+} from "@openfn/deploy";
+async function pullHandler(options, logger) {
+  try {
+    const config = mergeOverrides2(await getConfig2(options.configPath), options);
+    logger.always("Downloading project yaml and  state from instance");
+    const state = await getState(config.statePath);
+    const { data: new_state } = await getProject(config, state.id);
+    const url = new URL(`/download/yaml?id=${state.id}`, config.endpoint);
+    const res = await fetch(url);
+    await fs3.writeFile(path5.resolve(config.specPath), res.body);
+    await fs3.writeFile(path5.resolve(config.statePath), new_state);
+    logger.success("Project pulled successfully");
+    process.exitCode = 0;
+    return true;
+  } catch (error) {
+    throw error;
+  }
+}
+function mergeOverrides2(config, options) {
+  return {
+    ...config,
+    apiKey: pickFirst2(process.env["OPENFN_API_KEY"], config.apiKey),
+    endpoint: pickFirst2(process.env["OPENFN_ENDPOINT"], config.endpoint),
+    configPath: options.configPath,
+    requireConfirmation: pickFirst2(options.confirm, config.requireConfirmation)
+  };
+}
+function pickFirst2(...args) {
+  return args.find((arg) => arg !== void 0 && arg !== null);
+}
+var handler_default8 = pullHandler;
 
 // src/util/ensure-opts.ts
-import path5 from "node:path";
+import path6 from "node:path";
 var defaultLoggerOptions = {
   default: "default",
   job: "debug"
@@ -1059,7 +1151,7 @@ function ensureOpts(basePath = ".", opts) {
   }
   let baseDir = basePath;
   if (basePath.endsWith(".js")) {
-    baseDir = path5.dirname(basePath);
+    baseDir = path6.dirname(basePath);
     set2("jobPath", basePath);
   } else {
     set2("jobPath", `${baseDir}/job.js`);
@@ -1077,7 +1169,7 @@ function ensureOpts(basePath = ".", opts) {
 
 // src/util/print-versions.ts
 import { readFileSync as readFileSync3 } from "node:fs";
-import path6 from "node:path";
+import path7 from "node:path";
 import { getNameAndVersion as getNameAndVersion6 } from "@openfn/runtime";
 import { mainSymbols } from "figures";
 var NODE = "node.js";
@@ -1087,7 +1179,7 @@ var COMPILER2 = "compiler";
 var { triangleRightSmall: t } = mainSymbols;
 var loadVersionFromPath = (adaptorPath) => {
   try {
-    const pkg = JSON.parse(readFileSync3(path6.resolve(adaptorPath, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync3(path7.resolve(adaptorPath, "package.json"), "utf8"));
     return pkg.version;
   } catch (e) {
     return "unknown";
@@ -1155,16 +1247,18 @@ var handlers = {
   execute: handler_default,
   compile: handler_default2,
   test: handler_default3,
-  docgen: handler_default4,
-  docs: handler_default5,
-  metadata: handler_default6,
+  deploy: handler_default4,
+  docgen: handler_default5,
+  docs: handler_default6,
+  metadata: handler_default7,
+  pull: handler_default8,
   ["repo-clean"]: clean,
   ["repo-install"]: install,
   ["repo-pwd"]: pwd,
   ["repo-list"]: list,
   version: async (opts, logger) => print_versions_default(logger, opts)
 };
-var maybeEnsureOpts = (basePath, options) => /(^(execute|compile|test)$)|(repo-)/.test(options.command) ? ensureLogOpts(options) : ensureOpts(basePath, options);
+var maybeEnsureOpts = (basePath, options) => /(^(deploy|execute|compile|test)$)|(repo-)/.test(options.command) ? ensureLogOpts(options) : ensureOpts(basePath, options);
 var parse = async (basePath, options, log) => {
   const opts = maybeEnsureOpts(basePath, options);
   const logger = log || logger_default(CLI, opts);
@@ -1183,7 +1277,7 @@ var parse = async (basePath, options, log) => {
   } else if (opts.adaptors && opts.expandAdaptors) {
     expand_adaptors_default(opts);
   }
-  if (!/^(test|version)$/.test(opts.command) && !opts.repoDir) {
+  if (!/^(deploy|test|version)$/.test(opts.command) && !opts.repoDir) {
     logger.warn(
       "WARNING: no repo module dir found! Using the default (/tmp/repo)"
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfn/cli",
-  "version": "0.0.41",
+  "version": "0.2.0",
   "description": "CLI devtools for the openfn toolchain.",
   "engines": {
     "node": ">=18",
@@ -36,14 +36,15 @@
     "typescript": "^4.7.4"
   },
   "dependencies": {
-    "@openfn/compiler": "0.0.32",
-    "@openfn/describe-package": "0.0.16",
-    "@openfn/logger": "0.0.13",
-    "@openfn/runtime": "0.0.25",
     "figures": "^5.0.0",
     "rimraf": "^3.0.2",
     "treeify": "^1.1.0",
-    "yargs": "^17.5.1"
+    "yargs": "^17.5.1",
+    "@openfn/compiler": "0.0.32",
+    "@openfn/deploy": "0.2.0",
+    "@openfn/logger": "0.0.13",
+    "@openfn/describe-package": "0.0.16",
+    "@openfn/runtime": "0.0.26"
   },
   "files": [
     "dist",