@openfn/cli 1.20.3 → 1.21.0

package/dist/process/runner.js

@@ -21,13 +21,13 @@ var urlMap = {
   ["local"]: LOCAL_URL
 };
 var DEFAULT_ENV = "staging";
-var getURL = (options6) => {
-  if (options6.apolloUrl) {
-    if (options6.apolloUrl in urlMap) {
-      return urlMap[options6.apolloUrl];
+var getURL = (options7) => {
+  if (options7.apolloUrl) {
+    if (options7.apolloUrl in urlMap) {
+      return urlMap[options7.apolloUrl];
     }
-    if (options6.apolloUrl.startsWith("http")) {
-      return options6.apolloUrl;
+    if (options7.apolloUrl.startsWith("http")) {
+      return options7.apolloUrl;
     }
     throw new Error(`Unrecognised apollo URL`);
   }
@@ -52,14 +52,14 @@ var outputFiles = (files, logger) => {
 };
 
 // src/apollo/handler.ts
-var apolloHandler = async (options6, logger) => {
-  logger.always(`Calling Apollo service: ${options6.service}`);
-  const json = await loadPayload(logger, options6.payload);
-  const url2 = getURL(options6);
+var apolloHandler = async (options7, logger) => {
+  logger.always(`Calling Apollo service: ${options7.service}`);
+  const json = await loadPayload(logger, options7.payload);
+  const url2 = getURL(options7);
   logger.success(`Using apollo server at`, url2);
-  const result = await callApollo(url2, options6.service, json, logger);
+  const result = await callApollo(url2, options7.service, json, logger);
   if (result) {
-    await serializeOutput(options6, result, logger);
+    await serializeOutput(options7, result, logger);
   } else {
     logger.warn("No output returned from Apollo");
   }
@@ -79,15 +79,15 @@ var write = async (basePath, filePath, content, logger) => {
   await writeFile(dest, content);
   logger.success(`Wrote content to ${dest}`);
 };
-var serializeOutput = async (options6, result, logger) => {
-  if (options6.outputPath) {
-    if (result.files && !options6.outputPath.endsWith(".json")) {
+var serializeOutput = async (options7, result, logger) => {
+  if (options7.outputPath) {
+    if (result.files && !options7.outputPath.endsWith(".json")) {
       for (const p in result.files) {
-        await write(options6.outputPath, p, result.files[p], logger);
+        await write(options7.outputPath, p, result.files[p], logger);
       }
     } else {
       await write(
-        options6.outputPath,
+        options7.outputPath,
         "",
         JSON.stringify(result, null, 2),
         logger
@@ -133,14 +133,14 @@ var callApollo = async (apolloBaseUrl, serviceName, payload, logger) => {
     });
   });
 };
-var loadPayload = async (logger, path15) => {
-  if (!path15) {
+var loadPayload = async (logger, path17) => {
+  if (!path17) {
     logger.warn("No JSON payload provided");
     logger.warn("Most apollo services require JSON to be uploaded");
     return {};
   }
-  if (path15.endsWith(".json")) {
-    const str = await readFile(path15, "utf8");
+  if (path17.endsWith(".json")) {
+    const str = await readFile(path17, "utf8");
     const json = JSON.parse(str);
     logger.debug("Loaded JSON payload");
     return json;
@@ -148,6 +148,11 @@ var loadPayload = async (logger, path15) => {
 };
 var handler_default = apolloHandler;
 
+// src/execute/handler.ts
+import { yamlToJson as yamlToJson2 } from "@openfn/project";
+import { readFile as readFile3 } from "node:fs/promises";
+import path5 from "node:path";
+
 // src/execute/execute.ts
 import run, { NOTIFY_JOB_COMPLETE, getNameAndVersion } from "@openfn/runtime";
 
@@ -164,17 +169,17 @@ var namespaces = {
   [COMPILER]: "CMP",
   [JOB]: "JOB"
 };
-var createLogger2 = (name = "", options6) => {
-  const logOptions = options6.log || {};
+var createLogger2 = (name = "", options7) => {
+  const logOptions = options7.log || {};
   let json = false;
   let level = logOptions[name] || logOptions.default || "default";
-  if (options6.logJson) {
+  if (options7.logJson) {
     json = true;
   }
   return actualCreateLogger(namespaces[name] || name, {
     level,
     json,
-    sanitize: options6.sanitize || "none",
+    sanitize: options7.sanitize || "none",
     ...logOptions
   });
 };
@@ -185,8 +190,8 @@ var createNullLogger = () => createLogger2(void 0, { log: { default: "none" } })
 import fs from "node:fs";
 import path2 from "node:path";
 import { rmdir } from "node:fs/promises";
-var getCachePath = async (plan, options6, stepId) => {
-  const { baseDir } = options6;
+var getCachePath = async (plan, options7, stepId) => {
+  const { baseDir } = options7;
   const { name } = plan.workflow;
   const basePath = `${baseDir}/.cli-cache/${name}`;
   if (stepId) {
@@ -194,10 +199,10 @@ var getCachePath = async (plan, options6, stepId) => {
   }
   return path2.resolve(basePath);
 };
-var ensureGitIgnore = (options6) => {
-  if (!options6._hasGitIgnore) {
+var ensureGitIgnore = (options7) => {
+  if (!options7._hasGitIgnore) {
     const ignorePath = path2.resolve(
-      options6.baseDir,
+      options7.baseDir,
       ".cli-cache",
       ".gitignore"
     );
@@ -207,19 +212,19 @@ var ensureGitIgnore = (options6) => {
       fs.writeFileSync(ignorePath, "*");
     }
   }
-  options6._hasGitIgnore = true;
+  options7._hasGitIgnore = true;
 };
-var saveToCache = async (plan, stepId, output, options6, logger) => {
-  if (options6.cacheSteps) {
-    const cachePath = await getCachePath(plan, options6, stepId);
+var saveToCache = async (plan, stepId, output, options7, logger) => {
+  if (options7.cacheSteps) {
+    const cachePath = await getCachePath(plan, options7, stepId);
     fs.mkdirSync(path2.dirname(cachePath), { recursive: true });
-    ensureGitIgnore(options6);
+    ensureGitIgnore(options7);
     logger.info(`Writing ${stepId} output to ${cachePath}`);
     fs.writeFileSync(cachePath, JSON.stringify(output));
   }
 };
-var clearCache = async (plan, options6, logger) => {
-  const cacheDir = await getCachePath(plan, options6);
+var clearCache = async (plan, options7, logger) => {
+  const cacheDir = await getCachePath(plan, options7);
   try {
     await rmdir(cacheDir, { recursive: true });
     logger.info(`Cleared cache at ${cacheDir}`);
@@ -262,13 +267,13 @@ var execute_default = async (plan, input, opts, logger) => {
 };
 function parseAdaptors(plan) {
   const extractInfo = (specifier) => {
-    const [module, path15] = specifier.split("=");
+    const [module, path17] = specifier.split("=");
     const { name, version } = getNameAndVersion(module);
     const info = {
       name
     };
-    if (path15) {
-      info.path = path15;
+    if (path17) {
+      info.path = path17;
     }
     if (version) {
       info.version = version;
@@ -289,7 +294,7 @@ function parseAdaptors(plan) {
 // src/execute/serialize-output.ts
 import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
 import { dirname } from "node:path";
-var serializeOutput2 = async (options6, result, logger) => {
+var serializeOutput2 = async (options7, result, logger) => {
   let output = result;
   if (output && (output.configuration || output.data)) {
     const { configuration, ...rest } = result;
@@ -300,14 +305,14 @@ var serializeOutput2 = async (options6, result, logger) => {
   } else {
     output = JSON.stringify(output, void 0, 2);
   }
-  if (options6.outputStdout) {
+  if (options7.outputStdout) {
     logger.success(`Result: `);
     logger.always(output);
-  } else if (options6.outputPath) {
-    await mkdir2(dirname(options6.outputPath), { recursive: true });
-    logger.debug(`Writing output to ${options6.outputPath}`);
-    await writeFile2(options6.outputPath, output);
-    logger.success(`State written to ${options6.outputPath}`);
+  } else if (options7.outputPath) {
+    await mkdir2(dirname(options7.outputPath), { recursive: true });
+    logger.debug(`Writing output to ${options7.outputPath}`);
+    await writeFile2(options7.outputPath, output);
+    logger.success(`State written to ${options7.outputPath}`);
   }
   return output;
 };
@@ -326,6 +331,39 @@ var getAutoinstallTargets = (plan) => {
 };
 var get_autoinstall_targets_default = getAutoinstallTargets;
 
+// src/execute/apply-credential-map.ts
+var applyCredentialMap = (plan, map = {}, logger) => {
+  const stepsWithCredentialIds = plan.workflow.steps.filter(
+    (step) => typeof step.configuration === "string" && !step.configuration.endsWith(".json")
+  );
+  const unmapped = {};
+  for (const step of stepsWithCredentialIds) {
+    if (map[step.configuration]) {
+      logger?.debug(
+        `Applying credential ${step.configuration} to "${step.name ?? step.id}"`
+      );
+      step.configuration = map[step.configuration];
+    } else {
+      unmapped[step.configuration] = true;
+      delete step.configuration;
+    }
+  }
+  if (Object.keys(unmapped).length) {
+    logger?.warn(
+      `WARNING: credential IDs were found in the workflow, but values have not been provided:`
+    );
+    logger?.warn("  ", Object.keys(unmapped).join(","));
+    if (map) {
+      logger?.warn(
+        "If the workflow fails, add these credentials to the credential map"
+      );
+    } else {
+      logger?.warn("Pass a credential map with --credentials");
+    }
+  }
+};
+var apply_credential_map_default = applyCredentialMap;
+
 // src/repo/handler.ts
 import { exec } from "node:child_process";
 import treeify from "treeify";
@@ -371,16 +409,16 @@ var removePackage = async (packageSpecifier, repoDir, logger) => {
     logger.warn(`Failed to remove ${aliasedName}: ${error.message}`);
   }
 };
-var clean = async (options6, logger) => {
-  if (options6.repoDir) {
+var clean = async (options7, logger) => {
+  if (options7.repoDir) {
     const doIt = await logger.confirm(
-      `This will remove everything at ${options6.repoDir}. Do you wish to proceed?`,
-      options6.force
+      `This will remove everything at ${options7.repoDir}. Do you wish to proceed?`,
+      options7.force
     );
     if (doIt) {
       return new Promise((resolve) => {
-        logger.info(`Cleaning repo at ${options6.repoDir} `);
-        exec(`npm exec rimraf ${options6.repoDir}`, () => {
+        logger.info(`Cleaning repo at ${options7.repoDir} `);
+        exec(`npm exec rimraf ${options7.repoDir}`, () => {
           logger.success("Repo cleaned");
           resolve();
         });
@@ -391,12 +429,12 @@ var clean = async (options6, logger) => {
     logger.error("No repoDir path detected");
   }
 };
-var pwd = async (options6, logger) => {
+var pwd = async (options7, logger) => {
   logger.info(`OPENFN_REPO_DIR is set to ${process.env.OPENFN_REPO_DIR}`);
-  logger.success(`Repo working directory is: ${options6.repoDir}`);
+  logger.success(`Repo working directory is: ${options7.repoDir}`);
 };
-var getDependencyList = async (options6, _logger) => {
-  const pkg = await loadRepoPkg(options6.repoDir);
+var getDependencyList = async (options7, _logger) => {
+  const pkg = await loadRepoPkg(options7.repoDir);
   const result = {};
   if (pkg) {
     Object.keys(pkg.dependencies).forEach((key) => {
@@ -409,9 +447,9 @@ var getDependencyList = async (options6, _logger) => {
   }
   return result;
 };
-var list = async (options6, logger) => {
-  const tree = await getDependencyList(options6, logger);
-  await pwd(options6, logger);
+var list = async (options7, logger) => {
+  const tree = await getDependencyList(options7, logger);
+  await pwd(options7, logger);
   const output = {};
   Object.keys(tree).forEach((key) => {
     const versions = tree[key];
@@ -531,10 +569,10 @@ var stripVersionSpecifier = (specifier) => {
   return specifier;
 };
 var resolveSpecifierPath = async (pattern, repoDir, log2) => {
-  const [specifier, path15] = pattern.split("=");
-  if (path15) {
-    log2.debug(`Resolved ${specifier} to path: ${path15}`);
-    return path15;
+  const [specifier, path17] = pattern.split("=");
+  if (path17) {
+    log2.debug(`Resolved ${specifier} to path: ${path17}`);
+    return path17;
   }
   const repoPath = await getModulePath(specifier, repoDir, log2);
   if (repoPath) {
@@ -543,7 +581,7 @@ var resolveSpecifierPath = async (pattern, repoDir, log2) => {
   return null;
 };
 var loadTransformOptions = async (opts, log2) => {
-  const options6 = {
+  const options7 = {
     logger: log2 || logger_default(COMPILER, opts),
     trace: opts.trace
   };
@@ -553,12 +591,12 @@ var loadTransformOptions = async (opts, log2) => {
       let exports;
       const [specifier] = adaptorInput.split("=");
       log2.debug(`Trying to preload types for ${specifier}`);
-      const path15 = await resolveSpecifierPath(adaptorInput, opts.repoDir, log2);
-      if (path15) {
+      const path17 = await resolveSpecifierPath(adaptorInput, opts.repoDir, log2);
+      if (path17) {
         try {
-          exports = await preloadAdaptorExports(path15, log2);
+          exports = await preloadAdaptorExports(path17, log2);
         } catch (e) {
-          log2.error(`Failed to load adaptor typedefs from path ${path15}`);
+          log2.error(`Failed to load adaptor typedefs from path ${path17}`);
           log2.error(e);
         }
       }
@@ -571,12 +609,12 @@ var loadTransformOptions = async (opts, log2) => {
         exportAll: true
       });
     }
-    options6["add-imports"] = {
+    options7["add-imports"] = {
       ignore: opts.ignoreImports,
       adaptors: adaptorsConfig
     };
   }
-  return options6;
+  return options7;
 };
 
 // src/util/load-state.ts
@@ -595,7 +633,7 @@ var getUpstreamStepId = (plan, stepId) => {
   }
 };
 var load_state_default = async (plan, opts, log2, start) => {
-  const { stateStdin, statePath: statePath2 } = opts;
+  const { stateStdin, statePath } = opts;
   log2.debug("Loading state...");
   if (stateStdin) {
     try {
@@ -610,15 +648,15 @@ var load_state_default = async (plan, opts, log2, start) => {
       process.exit(1);
     }
   }
-  if (statePath2) {
+  if (statePath) {
     try {
-      const str = await fs2.readFile(statePath2, "utf8");
+      const str = await fs2.readFile(statePath, "utf8");
       const json = JSON.parse(str);
-      log2.success(`Loaded state from ${statePath2}`);
+      log2.success(`Loaded state from ${statePath}`);
       log2.debug("state:", json);
       return json;
     } catch (e) {
-      log2.warn(`Error loading state from ${statePath2}`);
+      log2.warn(`Error loading state from ${statePath}`);
       log2.warn(e);
     }
   }
@@ -669,12 +707,12 @@ var load_state_default = async (plan, opts, log2, start) => {
 };
 
 // src/util/validate-adaptors.ts
-var validateAdaptors = async (options6, logger) => {
-  if (options6.skipAdaptorValidation) {
+var validateAdaptors = async (options7, logger) => {
+  if (options7.skipAdaptorValidation) {
     return;
   }
-  const isPlan = options6.planPath || options6.workflowPath || options6.workflow;
-  const hasDeclaredAdaptors = options6.adaptors && options6.adaptors.length > 0;
+  const isPlan = options7.planPath || options7.workflowPath || options7.workflow;
+  const hasDeclaredAdaptors = options7.adaptors && options7.adaptors.length > 0;
   if (isPlan && hasDeclaredAdaptors) {
     logger.error("ERROR: adaptor and workflow provided");
     logger.error(
@@ -776,40 +814,47 @@ var mapAdaptorsToMonorepo = (monorepoPath = "", input = [], log2) => {
 };
 var map_adaptors_to_monorepo_default = mapAdaptorsToMonorepo;
 
+// src/util/resolve-path.ts
+import nodepath from "node:path";
+import os from "node:os";
+var resolve_path_default = (path17, root) => {
+  return path17.startsWith("~") ? path17.replace(`~`, os.homedir) : nodepath.resolve(root ?? "", path17);
+};
+
 // src/util/load-plan.ts
-var loadPlan = async (options6, logger) => {
-  const { workflowPath, planPath, expressionPath } = options6;
-  if (options6.path && /ya?ml$/.test(options6.path)) {
-    const content = await fs3.readFile(path4.resolve(options6.path), "utf-8");
+var loadPlan = async (options7, logger) => {
+  const { workflowPath, planPath, expressionPath } = options7;
+  if (options7.path && /ya?ml$/.test(options7.path)) {
+    const content = await fs3.readFile(path4.resolve(options7.path), "utf-8");
     const workflow2 = yamlToJson(content);
-    options6.baseDir = dirname2(options6.path);
-    return loadXPlan({ workflow: workflow2 }, options6, logger);
+    options7.baseDir = dirname2(options7.path);
+    return loadXPlan({ workflow: workflow2 }, options7, logger);
   }
-  if (options6.path && options6.workflow) {
-    options6.baseDir = options6.path;
-    return fromProject(options6.path, options6.workflow, options6, logger);
+  if (options7.path && options7.workflow) {
+    options7.baseDir = options7.path;
+    return fromProject(options7.path, options7.workflow, options7, logger);
   }
-  if (!expressionPath && !workflowPath && !/\.(js|json|yaml)+$/.test(options6.path || "") && !options6.workflow) {
-    const workflow2 = options6.path;
-    return fromProject(path4.resolve("."), workflow2, options6, logger);
+  if (!expressionPath && !workflowPath && !/\.(js|json|yaml)+$/.test(options7.path || "") && !options7.workflow) {
+    const workflow2 = options7.path;
+    return fromProject(path4.resolve("."), workflow2, options7, logger);
   }
   if (expressionPath) {
-    return loadExpression(options6, logger);
+    return loadExpression(options7, logger);
   }
   const jsonPath = planPath || workflowPath;
-  if (!options6.baseDir) {
-    options6.baseDir = path4.dirname(jsonPath);
+  if (!options7.baseDir) {
+    options7.baseDir = path4.dirname(jsonPath);
   }
   const json = await loadJson(jsonPath, logger);
   const defaultName = path4.parse(jsonPath).name;
   if (json.workflow) {
-    return loadXPlan(json, options6, logger, defaultName);
+    return loadXPlan(json, options7, logger, defaultName);
   } else {
-    return loadOldWorkflow(json, options6, logger, defaultName);
+    return loadOldWorkflow(json, options7, logger, defaultName);
   }
 };
 var load_plan_default = loadPlan;
-var fromProject = async (rootDir, workflowName, options6, logger) => {
+var fromProject = async (rootDir, workflowName, options7, logger) => {
   logger.debug("Loading Repo from ", path4.resolve(rootDir));
   const project = await Project.from("fs", { root: rootDir });
   logger.debug("Loading workflow ", workflowName);
@@ -817,7 +862,7 @@ var fromProject = async (rootDir, workflowName, options6, logger) => {
   if (!workflow2) {
     throw new Error(`Workflow "${workflowName}" not found`);
   }
-  return loadXPlan({ workflow: workflow2 }, options6, logger);
+  return loadXPlan({ workflow: workflow2 }, options7, logger);
 };
 var loadJson = async (workflowPath, logger) => {
   let text;
@@ -852,8 +897,8 @@ var maybeAssign = (a, b, keys) => {
     }
   });
 };
-var loadExpression = async (options6, logger) => {
-  const expressionPath = options6.expressionPath;
+var loadExpression = async (options7, logger) => {
+  const expressionPath = options7.expressionPath;
   logger.debug(`Loading expression from ${expressionPath}`);
   try {
     const expression = await fs3.readFile(expressionPath, "utf8");
@@ -861,19 +906,19 @@ var loadExpression = async (options6, logger) => {
     const step = {
       expression,
       // The adaptor should have been expanded nicely already, so we don't need intervene here
-      adaptors: options6.adaptors ?? []
+      adaptors: options7.adaptors ?? []
     };
     const wfOptions = {};
-    maybeAssign(options6, wfOptions, ["timeout"]);
+    maybeAssign(options7, wfOptions, ["timeout"]);
     const plan = {
       workflow: {
         name,
         steps: [step],
-        globals: options6.globals
+        globals: options7.globals
       },
       options: wfOptions
     };
-    return loadXPlan(plan, options6, logger);
+    return loadXPlan(plan, options7, logger);
   } catch (e) {
     abort_default(
       logger,
@@ -884,7 +929,7 @@ var loadExpression = async (options6, logger) => {
     return {};
   }
 };
-var loadOldWorkflow = async (workflow2, options6, logger, defaultName = "") => {
+var loadOldWorkflow = async (workflow2, options7, logger, defaultName = "") => {
   const plan = {
     workflow: {
       steps: workflow2.jobs
@@ -896,7 +941,7 @@ var loadOldWorkflow = async (workflow2, options6, logger, defaultName = "") => {
   if (workflow2.id) {
     plan.id = workflow2.id;
   }
-  const final = await loadXPlan(plan, options6, logger, defaultName);
+  const final = await loadXPlan(plan, options7, logger, defaultName);
   logger.warn("Converted workflow into new format:");
   logger.warn(final);
   return final;
@@ -904,7 +949,7 @@ var loadOldWorkflow = async (workflow2, options6, logger, defaultName = "") => {
 var fetchFile = async (fileInfo, log2) => {
   const { rootDir = "", filePath, name } = fileInfo;
   try {
-    const fullPath = filePath.startsWith("~") ? filePath : path4.resolve(rootDir, filePath);
+    const fullPath = resolve_path_default(filePath, rootDir);
     const result = await fs3.readFile(fullPath, "utf8");
     log2.debug("Loaded file", fullPath);
     return result;
@@ -988,7 +1033,42 @@ var ensureAdaptors = (plan) => {
     job.adaptors ??= [];
   });
 };
-var loadXPlan = async (plan, options6, logger, defaultName = "") => {
+var ensureCollections = (plan, {
+  endpoint: endpoint2 = "https://app.openfn.org",
+  version = "latest",
+  apiKey: apiKey2 = "null"
+} = {}, logger) => {
+  let collectionsFound = false;
+  Object.values(plan.workflow.steps).filter((step) => step.expression?.match(/(collections\.)/)).forEach((step) => {
+    const job = step;
+    if (!job.adaptors?.find(
+      (v) => v.startsWith("@openfn/language-collections")
+    )) {
+      collectionsFound = true;
+      job.adaptors ??= [];
+      job.adaptors.push(
+        `@openfn/language-collections@${version || "latest"}`
+      );
+      job.configuration = Object.assign({}, job.configuration, {
+        collections_endpoint: `${endpoint2}/collections`,
+        collections_token: apiKey2
+      });
+    }
+  });
+  if (collectionsFound) {
+    if (!apiKey2 || apiKey2 === "null") {
+      logger?.warn(
+        "WARNING: collections API was not set. Pass --api-key or OPENFN_API_KEY"
+      );
+    }
+    logger?.info(
+      `Configured collections to use endpoint ${endpoint2} and API Key ending with ${apiKey2?.substring(
+        apiKey2.length - 10
+      )}`
+    );
+  }
+};
+var loadXPlan = async (plan, options7, logger, defaultName = "") => {
   if (!plan.options) {
     plan.options = {};
   }
@@ -996,22 +1076,31 @@ var loadXPlan = async (plan, options6, logger, defaultName = "") => {
     plan.workflow.name = defaultName;
   }
   ensureAdaptors(plan);
-  if (options6.globals)
-    plan.workflow.globals = options6.globals;
-  await importGlobals(plan, options6.baseDir, logger);
-  await importExpressions(plan, options6.baseDir, logger);
-  if (options6.expandAdaptors) {
+  ensureCollections(
+    plan,
+    {
+      version: options7.collectionsVersion,
+      apiKey: options7.apiKey,
+      endpoint: options7.collectionsEndpoint
+    },
+    logger
+  );
+  if (options7.globals)
+    plan.workflow.globals = options7.globals;
+  await importGlobals(plan, options7.baseDir, logger);
+  await importExpressions(plan, options7.baseDir, logger);
+  if (options7.expandAdaptors) {
     expand_adaptors_default(plan);
   }
-  await map_adaptors_to_monorepo_default(options6.monorepoPath, plan, logger);
-  maybeAssign(options6, plan.options, ["timeout", "start"]);
+  await map_adaptors_to_monorepo_default(options7.monorepoPath, plan, logger);
+  maybeAssign(options7, plan.options, ["timeout", "start"]);
   logger.info(`Loaded workflow ${plan.workflow.name ?? ""}`);
   return plan;
 };
 
 // src/util/assert-path.ts
-var assert_path_default = (path15) => {
-  if (!path15) {
+var assert_path_default = (path17) => {
+  if (!path17) {
     console.error("ERROR: no path provided!");
     console.error("\nUsage:");
     console.error("  open path/to/job");
@@ -1047,7 +1136,7 @@ var fuzzy_match_step_default = (plan, stepPattern) => {
 
 // src/util/validate-plan.ts
 var assertWorkflowStructure = (plan, logger) => {
-  const { workflow: workflow2, options: options6 } = plan;
+  const { workflow: workflow2, options: options7 } = plan;
   if (!workflow2 || typeof workflow2 !== "object") {
     throw new Error(`Missing or invalid "workflow" key in execution plan`);
   }
@@ -1060,7 +1149,7 @@ var assertWorkflowStructure = (plan, logger) => {
   workflow2.steps.forEach((step, index) => {
     assertStepStructure(step, index);
   });
-  assertOptionsStructure(options6, logger);
+  assertOptionsStructure(options7, logger);
 };
 var assertStepStructure = (step, index) => {
   const allowedKeys = [
@@ -1087,9 +1176,9 @@ var assertStepStructure = (step, index) => {
     );
   }
 };
-var assertOptionsStructure = (options6 = {}, logger) => {
+var assertOptionsStructure = (options7 = {}, logger) => {
   const allowedKeys = ["timeout", "stepTimeout", "start", "end", "sanitize"];
-  for (const key in options6) {
+  for (const key in options7) {
     if (!allowedKeys.includes(key)) {
       logger.warn(`Unrecognized option "${key}" in options object`);
     }
@@ -1145,17 +1234,41 @@ var matchStep = (plan, stepPattern, stepName, logger) => {
   }
   return "";
 };
-var executeHandler = async (options6, logger) => {
+var loadAndApplyCredentialMap = async (plan, options7, logger) => {
+  let creds = {};
+  if (options7.credentials) {
+    try {
+      const credsRaw = await readFile3(
+        path5.resolve(options7.credentials),
+        "utf8"
+      );
+      if (options7.credentials.endsWith(".json")) {
+        creds = JSON.parse(credsRaw);
+      } else {
+        creds = yamlToJson2(credsRaw);
+      }
+    } catch (e) {
+      logger.error("Error processing credential map:");
+      logger.error(e);
+      process.exitCode = 1;
+      return;
+    }
+    logger.info("Credential map loaded ");
+  }
+  return apply_credential_map_default(plan, creds, logger);
+};
+var executeHandler = async (options7, logger) => {
   const start = (/* @__PURE__ */ new Date()).getTime();
-  assert_path_default(options6.path);
-  await validate_adaptors_default(options6, logger);
-  let plan = await load_plan_default(options6, logger);
+  assert_path_default(options7.path);
+  await validate_adaptors_default(options7, logger);
+  let plan = await load_plan_default(options7, logger);
   validate_plan_default(plan, logger);
-  if (options6.cacheSteps) {
-    await clearCache(plan, options6, logger);
+  await loadAndApplyCredentialMap(plan, options7, logger);
+  if (options7.cacheSteps) {
+    await clearCache(plan, options7, logger);
   }
   const moduleResolutions = {};
-  const { repoDir, monorepoPath, autoinstall } = options6;
+  const { repoDir, monorepoPath, autoinstall } = options7;
   if (autoinstall) {
     if (monorepoPath) {
       logger.warn("Skipping auto-install as monorepo is being used");
@@ -1163,13 +1276,13 @@ var executeHandler = async (options6, logger) => {
       const autoInstallTargets = get_autoinstall_targets_default(plan);
       if (autoInstallTargets.length) {
         logger.info("Auto-installing language adaptors");
-        options6.adaptors = await install(
+        options7.adaptors = await install(
           { packages: autoInstallTargets, repoDir },
           logger
         );
-        if (autoInstallTargets.length === options6.adaptors.length) {
+        if (autoInstallTargets.length === options7.adaptors.length) {
           for (let i = 0; i < autoInstallTargets.length; i++) {
-            moduleResolutions[autoInstallTargets[i]] = options6.adaptors[i];
+            moduleResolutions[autoInstallTargets[i]] = options7.adaptors[i];
           }
         }
       }
@@ -1177,35 +1290,35 @@ var executeHandler = async (options6, logger) => {
   }
   let customStart;
   let customEnd;
-  if (options6.only) {
-    const step = matchStep(plan, options6.only, "only", logger);
+  if (options7.only) {
+    const step = matchStep(plan, options7.only, "only", logger);
     customStart = step;
     customEnd = step;
-    logger.always(`Only running workflow step "${options6.start}"`);
+    logger.always(`Only running workflow step "${options7.start}"`);
   } else {
-    if (options6.start) {
+    if (options7.start) {
       customStart = matchStep(
         plan,
-        options6.start ?? plan.options.start,
+        options7.start ?? plan.options.start,
         "start",
         logger
       );
-      logger.info(`Starting workflow from step "${options6.start}"`);
+      logger.info(`Starting workflow from step "${options7.start}"`);
     }
-    if (options6.end) {
+    if (options7.end) {
       customEnd = matchStep(
         plan,
-        options6.end ?? plan.options.end,
+        options7.end ?? plan.options.end,
         "end",
         logger
       );
-      logger.always(`Ending workflow at step "${options6.end}"`);
+      logger.always(`Ending workflow at step "${options7.end}"`);
     }
   }
-  const state = await load_state_default(plan, options6, logger, customStart);
+  const state = await load_state_default(plan, options7, logger, customStart);
   plan = override_plan_adaptors_default(plan, moduleResolutions);
-  if (options6.compile) {
-    plan = await compile_default(plan, options6, logger);
+  if (options7.compile) {
+    plan = await compile_default(plan, options7, logger);
   } else {
     logger.info("Skipping compilation as noCompile is set");
   }
@@ -1219,13 +1332,13 @@ var executeHandler = async (options6, logger) => {
     workflow: plan.workflow
   };
   try {
-    const result = await execute_default(finalPlan, state, options6, logger);
-    if (options6.cacheSteps) {
+    const result = await execute_default(finalPlan, state, options7, logger);
+    if (options7.cacheSteps) {
       logger.success(
         "Cached output written to ./cli-cache (see info logs for details)"
       );
     }
-    await serialize_output_default(options6, result, logger);
+    await serialize_output_default(options7, result, logger);
     const duration = printDuration((/* @__PURE__ */ new Date()).getTime() - start);
     if (result?.errors) {
       logger.warn(
@@ -1248,55 +1361,55 @@ var handler_default2 = executeHandler;
 
 // src/compile/handler.ts
 import { writeFile as writeFile3 } from "node:fs/promises";
-var compileHandler = async (options6, logger) => {
-  assert_path_default(options6.path);
+var compileHandler = async (options7, logger) => {
+  assert_path_default(options7.path);
   let result;
-  if (options6.expressionPath) {
-    const { code } = await compile_default(options6.expressionPath, options6, logger);
+  if (options7.expressionPath) {
+    const { code } = await compile_default(options7.expressionPath, options7, logger);
     result = code;
   } else {
-    const plan = await load_plan_default(options6, logger);
-    const compiledPlan = await compile_default(plan, options6, logger);
+    const plan = await load_plan_default(options7, logger);
+    const compiledPlan = await compile_default(plan, options7, logger);
     result = JSON.stringify(compiledPlan, null, 2);
   }
-  if (options6.outputStdout) {
+  if (options7.outputStdout) {
     logger.success("Result:\n\n" + result);
   } else {
-    await writeFile3(options6.outputPath, result);
-    logger.success(`Compiled to ${options6.outputPath}`);
+    await writeFile3(options7.outputPath, result);
+    logger.success(`Compiled to ${options7.outputPath}`);
   }
 };
 var handler_default3 = compileHandler;
 
 // src/collections/handler.ts
-import path6 from "node:path";
-import { readFile as readFile3, writeFile as writeFile4 } from "node:fs/promises";
+import path7 from "node:path";
+import { readFile as readFile4, writeFile as writeFile4 } from "node:fs/promises";
 
 // src/collections/request.ts
-import path5 from "node:path";
+import path6 from "node:path";
 import { request } from "undici";
 var DEFAULT_PAGE_SIZE = 1e3;
-var request_default = async (method, options6, logger) => {
-  const base = options6.lightning || process.env.OPENFN_ENDPOINT || "https://app.openfn.org";
-  const url2 = path5.join(base, "/collections", options6.collectionName);
+var request_default = async (method, options7, logger) => {
+  const base = options7.lightning || process.env.OPENFN_ENDPOINT || "https://app.openfn.org";
+  const url2 = path6.join(base, "/collections", options7.collectionName);
   logger.debug("Calling Collections server at ", url2);
   const headers = {
-    Authorization: `Bearer ${options6.token}`
+    Authorization: `Bearer ${options7.token}`
   };
   const query = Object.assign(
     {
-      key: options6.key,
-      limit: options6.pageSize || DEFAULT_PAGE_SIZE
+      key: options7.key,
+      limit: options7.pageSize || DEFAULT_PAGE_SIZE
     },
-    options6.query
+    options7.query
   );
   const args = {
     headers,
     method,
     query
   };
-  if (options6.data) {
-    args.body = JSON.stringify(options6.data);
+  if (options7.data) {
+    args.body = JSON.stringify(options7.data);
     headers["content-type"] = "application/json";
   }
   let result = {};
@@ -1307,11 +1420,11 @@ var request_default = async (method, options6, logger) => {
     if (cursor) {
       query.cursor = cursor;
     }
-    if (options6.limit) {
-      limit = options6.limit;
+    if (options7.limit) {
+      limit = options7.limit;
       query.limit = Math.min(
-        options6.pageSize || DEFAULT_PAGE_SIZE,
-        options6.limit - count
+        options7.pageSize || DEFAULT_PAGE_SIZE,
+        options7.limit - count
       );
     }
     try {
@@ -1405,7 +1518,7 @@ var ensureToken = (opts, logger) => {
     }
   }
 };
-var buildQuery = (options6) => {
+var buildQuery = (options7) => {
   const map = {
     createdBefore: "created_before",
     createdAfter: "created_after",
@@ -1414,34 +1527,34 @@ var buildQuery = (options6) => {
   };
   const query = {};
   Object.keys(map).forEach((key) => {
-    if (options6[key]) {
-      query[map[key]] = options6[key];
+    if (options7[key]) {
+      query[map[key]] = options7[key];
     }
   });
   return query;
 };
-var get = async (options6, logger) => {
-  ensureToken(options6, logger);
-  const multiMode = options6.key.includes("*");
+var get = async (options7, logger) => {
+  ensureToken(options7, logger);
+  const multiMode = options7.key.includes("*");
   if (multiMode) {
     logger.info(
-      `Fetching multiple items from collection "${options6.collectionName}" with pattern ${options6.key}`
+      `Fetching multiple items from collection "${options7.collectionName}" with pattern ${options7.key}`
     );
   } else {
     logger.info(
-      `Fetching "${options6.key}" from collection "${options6.collectionName}"`
+      `Fetching "${options7.key}" from collection "${options7.collectionName}"`
     );
   }
   let result = await request_default(
     "GET",
     {
-      lightning: options6.endpoint,
-      token: options6.token,
-      pageSize: options6.pageSize,
-      limit: options6.limit,
-      key: options6.key,
-      collectionName: options6.collectionName,
-      query: buildQuery(options6)
+      lightning: options7.endpoint,
+      token: options7.token,
+      pageSize: options7.pageSize,
+      limit: options7.limit,
+      key: options7.key,
+      collectionName: options7.collectionName,
+      query: buildQuery(options7)
     },
     logger
   );
@@ -1449,76 +1562,76 @@ var get = async (options6, logger) => {
     logger.success(`Fetched ${Object.keys(result).length} items!`);
   } else {
     result = Object.values(result)[0];
-    logger.success(`Fetched ${options6.key}`);
+    logger.success(`Fetched ${options7.key}`);
   }
-  if (options6.outputPath) {
+  if (options7.outputPath) {
     const content = JSON.stringify(
       result,
       null,
-      options6.pretty ? 2 : void 0
+      options7.pretty ? 2 : void 0
     );
-    await writeFile4(options6.outputPath, content);
-    logger.always(`Wrote items to ${options6.outputPath}`);
+    await writeFile4(options7.outputPath, content);
+    logger.always(`Wrote items to ${options7.outputPath}`);
   } else {
     logger.print(result);
   }
 };
-var set = async (options6, logger) => {
-  if (options6.key && options6.items) {
+var set = async (options7, logger) => {
+  if (options7.key && options7.items) {
     throwAbortableError(
       "ARGUMENT_ERROR: arguments for key and items were provided",
       "If upserting multiple items with --items, do not pass a key"
     );
   }
-  ensureToken(options6, logger);
-  logger.info(`Upserting items to collection "${options6.collectionName}"`);
+  ensureToken(options7, logger);
+  logger.info(`Upserting items to collection "${options7.collectionName}"`);
   const items = [];
-  if (options6.items) {
-    const resolvedPath = path6.resolve(options6.items);
+  if (options7.items) {
+    const resolvedPath = path7.resolve(options7.items);
     logger.debug("Loading items from ", resolvedPath);
-    const data = await readFile3(resolvedPath, "utf8");
+    const data = await readFile4(resolvedPath, "utf8");
     const obj = JSON.parse(data);
     Object.entries(obj).forEach(([key, value]) => {
       items.push({ key, value: JSON.stringify(value) });
     });
     logger.info(`Upserting ${items.length} items`);
-  } else if (options6.key && options6.value) {
-    const resolvedPath = path6.resolve(options6.value);
+  } else if (options7.key && options7.value) {
+    const resolvedPath = path7.resolve(options7.value);
     logger.debug("Loading value from ", resolvedPath);
-    const data = await readFile3(path6.resolve(options6.value), "utf8");
+    const data = await readFile4(path7.resolve(options7.value), "utf8");
     const value = JSON.stringify(JSON.parse(data));
-    items.push({ key: options6.key, value });
-    logger.info(`Upserting data to "${options6.key}"`);
+    items.push({ key: options7.key, value });
+    logger.info(`Upserting data to "${options7.key}"`);
   } else {
     throw new Error("INVALID_ARGUMENTS");
   }
   const result = await request_default(
     "POST",
     {
-      lightning: options6.endpoint,
-      token: options6.token,
-      key: options6.key,
-      collectionName: options6.collectionName,
+      lightning: options7.endpoint,
+      token: options7.token,
+      key: options7.key,
+      collectionName: options7.collectionName,
       data: { items }
     },
     logger
   );
   logger.success(`Upserted ${result.upserted} items!`);
 };
-var remove = async (options6, logger) => {
-  ensureToken(options6, logger);
+var remove = async (options7, logger) => {
+  ensureToken(options7, logger);
   logger.info(
-    `Removing "${options6.key}" from collection "${options6.collectionName}"`
+    `Removing "${options7.key}" from collection "${options7.collectionName}"`
   );
-  if (options6.dryRun) {
+  if (options7.dryRun) {
     logger.info("--dry-run passed: fetching affected items");
     let result = await request_default(
       "GET",
       {
-        lightning: options6.endpoint,
-        token: options6.token,
-        key: options6.key,
-        collectionName: options6.collectionName
+        lightning: options7.endpoint,
+        token: options7.token,
+        key: options7.key,
+        collectionName: options7.collectionName
       },
       logger
     );
@@ -1530,11 +1643,11 @@ var remove = async (options6, logger) => {
     let result = await request_default(
       "DELETE",
       {
-        lightning: options6.endpoint,
-        token: options6.token,
-        key: options6.key,
-        collectionName: options6.collectionName,
-        query: buildQuery(options6)
+        lightning: options7.endpoint,
+        token: options7.token,
+        key: options7.key,
+        collectionName: options7.collectionName,
+        query: buildQuery(options7)
       },
       logger
     );
@@ -1548,9 +1661,9 @@ var handler_default4 = {
 };
 
 // src/test/handler.ts
-var testHandler = async (options6, logger) => {
+var testHandler = async (options7, logger) => {
   logger.log("Running test workflow...");
-  const opts = { ...options6 };
+  const opts = { ...options7 };
   opts.compile = true;
   opts.adaptors = [];
   const plan = {
@@ -1617,7 +1730,7 @@ import Project2 from "@openfn/project";
 import { deployProject } from "@openfn/deploy";
 
 // src/projects/util.ts
-import path7 from "node:path";
+import path8 from "node:path";
 import { mkdir as mkdir3, writeFile as writeFile5 } from "node:fs/promises";
 
 // src/errors.ts
@@ -1628,17 +1741,17 @@ var CLIError = class extends Error {
 };
 
 // src/projects/util.ts
-var loadAppAuthConfig = (options6, logger) => {
+var loadAppAuthConfig = (options7, logger) => {
   const { OPENFN_API_KEY, OPENFN_ENDPOINT } = process.env;
   const config2 = {
-    apiKey: options6.apiKey,
-    endpoint: options6.endpoint
+    apiKey: options7.apiKey,
+    endpoint: options7.endpoint
   };
-  if (!options6.apiKey && OPENFN_API_KEY) {
+  if (!options7.apiKey && OPENFN_API_KEY) {
     logger.info("Using OPENFN_API_KEY environment variable");
     config2.apiKey = OPENFN_API_KEY;
   }
-  if (!options6.endpoint && OPENFN_ENDPOINT) {
+  if (!options7.endpoint && OPENFN_ENDPOINT) {
     logger.info("Using OPENFN_ENDPOINT environment variable");
     config2.endpoint = OPENFN_ENDPOINT;
   }
@@ -1651,7 +1764,7 @@ var ensureExt = (filePath, ext) => {
   return filePath;
 };
 var serialize = async (project, outputPath2, formatOverride, dryRun = false) => {
-  const root = path7.dirname(outputPath2);
+  const root = path8.dirname(outputPath2);
   await mkdir3(root, { recursive: true });
   const format = formatOverride ?? project.config?.formats.project;
   const output = project?.serialize("project", { format });
@@ -1670,41 +1783,38 @@ var serialize = async (project, outputPath2, formatOverride, dryRun = false) =>
   }
   return finalPath;
 };
-var getLightningUrl = (config2, path15 = "", snapshots2) => {
+var getLightningUrl = (endpoint2, path17 = "", snapshots2) => {
   const params = new URLSearchParams();
   snapshots2?.forEach((snapshot) => params.append("snapshots[]", snapshot));
-  return new URL(
-    `/api/provision/${path15}?${params.toString()}`,
-    config2.endpoint
-  );
+  return new URL(`/api/provision/${path17}?${params.toString()}`, endpoint2);
 };
-async function getProject(logger, config2, projectId2, snapshots2) {
-  const url2 = getLightningUrl(config2, projectId2, snapshots2);
-  logger.info(`Checking ${url2} for existing project`);
+async function fetchProject(endpoint2, apiKey2, projectId, logger, snapshots2) {
+  const url2 = getLightningUrl(endpoint2, projectId, snapshots2);
+  logger?.info(`Checking ${url2} for existing project`);
   try {
     const response = await fetch(url2, {
       headers: {
-        Authorization: `Bearer ${config2.apiKey}`,
+        Authorization: `Bearer ${apiKey2}`,
         Accept: "application/json"
       }
     });
     if (!response.ok) {
       if (response.status === 401 || response.status === 403) {
         throw new CLIError(
-          `Failed to authorize request with endpoint ${config2.endpoint}, got ${response.status} ${response.statusText}`
+          `Failed to authorize request with endpoint ${endpoint2}, got ${response.status} ${response.statusText}`
         );
       }
       if (response.status === 404) {
-        throw new CLIError(`Project not found: ${projectId2}`);
+        throw new CLIError(`Project not found: ${projectId}`);
       }
       throw new CLIError(
-        `Failed to fetch project ${projectId2}: ${response.statusText}`
+        `Failed to fetch project ${projectId}: ${response.statusText}`
       );
     }
-    logger.info("Project found");
+    logger?.info(`Project retrieved from ${endpoint2}`);
     return response.json();
   } catch (error) {
-    handleCommonErrors(config2, error);
+    handleCommonErrors({ endpoint: endpoint2, apiKey: apiKey2 }, error);
     throw error;
   }
 }
@@ -1722,9 +1832,11 @@ var DeployError = class extends Error {
 };
 
 // src/deploy/beta.ts
-async function handler(options6, logger) {
-  const config2 = loadAppAuthConfig(options6, logger);
-  const project = await Project2.from("fs", { root: options6.workspace || "." });
+async function handler(options7, logger) {
+  const config2 = loadAppAuthConfig(options7, logger);
+  const project = await Project2.from("fs", {
+    root: options7.workspace || "."
+  });
   const state = project.serialize("state", { format: "json" });
   logger.debug("Converted local project to app state:");
   logger.debug(JSON.stringify(state, null, 2));
@@ -1736,15 +1848,15 @@ async function handler(options6, logger) {
 
 // src/deploy/handler.ts
 var actualDeploy = deploy;
-async function deployHandler(options6, logger, deployFn = actualDeploy) {
-  if (options6.beta) {
-    return handler(options6, logger);
+async function deployHandler(options7, logger, deployFn = actualDeploy) {
+  if (options7.beta) {
+    return handler(options7, logger);
   }
   try {
-    const config2 = mergeOverrides(await getConfig(options6.configPath), options6);
+    const config2 = mergeOverrides(await getConfig(options7.configPath), options7);
     logger.debug("Deploying with config", JSON.stringify(config2, null, 2));
-    if (options6.confirm === false) {
-      config2.requireConfirmation = options6.confirm;
+    if (options7.confirm === false) {
+      config2.requireConfirmation = options7.confirm;
     }
     if (process.env["OPENFN_API_KEY"]) {
       logger.info("Using OPENFN_API_KEY environment variable");
@@ -1769,15 +1881,15 @@ async function deployHandler(options6, logger, deployFn = actualDeploy) {
     throw error;
   }
 }
-function mergeOverrides(config2, options6) {
+function mergeOverrides(config2, options7) {
   return {
     ...config2,
     apiKey: pickFirst(process.env["OPENFN_API_KEY"], config2.apiKey),
     endpoint: pickFirst(process.env["OPENFN_ENDPOINT"], config2.endpoint),
-    statePath: pickFirst(options6.statePath, config2.statePath),
-    specPath: pickFirst(options6.projectPath, config2.specPath),
-    configPath: options6.configPath,
-    requireConfirmation: pickFirst(options6.confirm, config2.requireConfirmation)
+    statePath: pickFirst(options7.statePath, config2.statePath),
+    specPath: pickFirst(options7.projectPath, config2.specPath),
+    configPath: options7.configPath,
+    requireConfirmation: pickFirst(options7.confirm, config2.requireConfirmation)
   };
 }
 function pickFirst(...args) {
@@ -1788,28 +1900,28 @@ var handler_default6 = deployHandler;
 // src/docgen/handler.ts
 import { writeFile as writeFile6 } from "node:fs/promises";
 import { readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
-import path8 from "node:path";
+import path9 from "node:path";
 import { describePackage } from "@openfn/describe-package";
 import { getNameAndVersion as getNameAndVersion4 } from "@openfn/runtime";
 var RETRY_DURATION = 500;
 var RETRY_COUNT = 20;
 var TIMEOUT_MS = 1e3 * 60;
 var actualDocGen = (specifier) => describePackage(specifier, {});
-var ensurePath = (filePath) => mkdirSync(path8.dirname(filePath), { recursive: true });
-var generatePlaceholder = (path15) => {
-  writeFileSync(path15, `{ "loading": true, "timestamp": ${Date.now()}}`);
+var ensurePath = (filePath) => mkdirSync(path9.dirname(filePath), { recursive: true });
+var generatePlaceholder = (path17) => {
+  writeFileSync(path17, `{ "loading": true, "timestamp": ${Date.now()}}`);
 };
 var finish = (logger, resultPath) => {
   logger.success("Done! Docs can be found at:\n");
-  logger.print(`  ${path8.resolve(resultPath)}`);
+  logger.print(`  ${path9.resolve(resultPath)}`);
 };
-var generateDocs = async (specifier, path15, docgen, logger) => {
+var generateDocs = async (specifier, path17, docgen, logger) => {
   const result = await docgen(specifier);
-  await writeFile6(path15, JSON.stringify(result, null, 2));
-  finish(logger, path15);
-  return path15;
+  await writeFile6(path17, JSON.stringify(result, null, 2));
+  finish(logger, path17);
+  return path17;
 };
-var waitForDocs = async (docs, path15, logger, retryDuration = RETRY_DURATION) => {
+var waitForDocs = async (docs, path17, logger, retryDuration = RETRY_DURATION) => {
   try {
     if (docs.hasOwnProperty("loading")) {
       logger.info("Docs are being loaded by another process. Waiting.");
@@ -1821,27 +1933,27 @@ var waitForDocs = async (docs, path15, logger, retryDuration = RETRY_DURATION) =
             clearInterval(i);
             reject(new Error("Timed out waiting for docs to load"));
           }
-          const updated = JSON.parse(readFileSync(path15, "utf8"));
+          const updated = JSON.parse(readFileSync(path17, "utf8"));
           if (!updated.hasOwnProperty("loading")) {
             logger.info("Docs found!");
             clearInterval(i);
-            resolve(path15);
+            resolve(path17);
           }
           count++;
         }, retryDuration);
       });
     } else {
-      logger.info(`Docs already written to cache at ${path15}`);
-      finish(logger, path15);
-      return path15;
+      logger.info(`Docs already written to cache at ${path17}`);
+      finish(logger, path17);
+      return path17;
     }
   } catch (e) {
     logger.error("Existing doc JSON corrupt. Aborting");
     throw e;
   }
 };
-var docgenHandler = (options6, logger, docgen = actualDocGen, retryDuration = RETRY_DURATION) => {
-  const { specifier, repoDir } = options6;
+var docgenHandler = (options7, logger, docgen = actualDocGen, retryDuration = RETRY_DURATION) => {
+  const { specifier, repoDir } = options7;
   const { version } = getNameAndVersion4(specifier);
   if (!version) {
     logger.error("Error: No version number detected");
@@ -1850,28 +1962,28 @@ var docgenHandler = (options6, logger, docgen = actualDocGen, retryDuration = RE
     process.exit(9);
   }
   logger.success(`Generating docs for ${specifier}`);
-  const path15 = `${repoDir}/docs/${specifier}.json`;
-  ensurePath(path15);
+  const path17 = `${repoDir}/docs/${specifier}.json`;
+  ensurePath(path17);
   const handleError2 = () => {
     logger.info("Removing placeholder");
-    rmSync(path15);
+    rmSync(path17);
   };
   try {
-    const existing = readFileSync(path15, "utf8");
+    const existing = readFileSync(path17, "utf8");
     const json = JSON.parse(existing);
     if (json && json.timeout && Date.now() - json.timeout >= TIMEOUT_MS) {
       logger.info(`Expired placeholder found. Removing.`);
-      rmSync(path15);
+      rmSync(path17);
       throw new Error("TIMEOUT");
     }
-    return waitForDocs(json, path15, logger, retryDuration);
+    return waitForDocs(json, path17, logger, retryDuration);
   } catch (e) {
     if (e.message !== "TIMEOUT") {
-      logger.info(`Docs JSON not found at ${path15}`);
+      logger.info(`Docs JSON not found at ${path17}`);
     }
     logger.debug("Generating placeholder");
-    generatePlaceholder(path15);
-    return generateDocs(specifier, path15, docgen, logger).catch((e2) => {
+    generatePlaceholder(path17);
+    return generateDocs(specifier, path17, docgen, logger).catch((e2) => {
       logger.error("Error generating documentation");
       logger.error(e2);
       handleError2();
@@ -1881,7 +1993,7 @@ var docgenHandler = (options6, logger, docgen = actualDocGen, retryDuration = RE
 var handler_default7 = docgenHandler;
 
 // src/docs/handler.ts
-import { readFile as readFile4 } from "node:fs/promises";
+import { readFile as readFile5 } from "node:fs/promises";
 import c from "chalk";
 import { getNameAndVersion as getNameAndVersion5, getLatestVersion } from "@openfn/runtime";
 var describeFn = (adaptorName, fn) => [
@@ -1910,8 +2022,8 @@ ${data.functions.map(
   (fn) => `  ${c.yellow(fn.name)} (${fn.parameters.map((p) => p.name).join(", ")})`
 ).sort().join("\n")}
 `;
-var docsHandler = async (options6, logger) => {
-  const { adaptor, operation, repoDir } = options6;
+var docsHandler = async (options7, logger) => {
+  const { adaptor, operation, repoDir } = options7;
   const adaptors = expand_adaptors_default([adaptor]);
   const [adaptorName] = adaptors;
   let { name, version } = getNameAndVersion5(adaptorName);
@@ -1922,7 +2034,7 @@ var docsHandler = async (options6, logger) => {
     logger.success(`Showing docs for ${adaptorName} v${version}`);
   }
   logger.info("Generating/loading documentation...");
-  const path15 = await handler_default7(
+  const path17 = await handler_default7(
     {
       specifier: `${name}@${version}`,
       repoDir
@@ -1931,8 +2043,8 @@ var docsHandler = async (options6, logger) => {
     createNullLogger()
   );
   let didError = false;
-  if (path15) {
-    const source = await readFile4(path15, "utf8");
+  if (path17) {
+    const source = await readFile5(path17, "utf8");
     const data = JSON.parse(source);
     let desc;
     if (operation) {
@@ -1970,20 +2082,20 @@ var handler_default8 = docsHandler;
 // src/metadata/cache.ts
 import { getNameAndVersion as getNameAndVersion6 } from "@openfn/runtime";
 import { createHash } from "node:crypto";
-import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile7, readdir, rm } from "node:fs/promises";
-import path9 from "node:path";
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile7, readdir, rm } from "node:fs/promises";
+import path10 from "node:path";
 var UNSUPPORTED_FILE_NAME = "unsupported.json";
 var getCachePath2 = (repoDir, key) => {
-  const base = path9.join(repoDir, "meta");
+  const base = path10.join(repoDir, "meta");
   if (key) {
-    return path9.join(base, key.endsWith(".json") ? key : `${key}.json`);
+    return path10.join(base, key.endsWith(".json") ? key : `${key}.json`);
   }
   return base;
 };
 var getCache = async (repoDir, key) => {
   try {
     const cachePath = getCachePath2(repoDir, key);
-    const content = await readFile5(cachePath, "utf8");
+    const content = await readFile6(cachePath, "utf8");
     return JSON.parse(content);
   } catch (e) {
     return null;
@@ -2010,7 +2122,7 @@ var generateKey = (config2, adaptor) => {
 var get2 = async (repoPath, key) => {
   const p = getCachePath2(repoPath, key);
   try {
-    const result = await readFile5(p, "utf8");
+    const result = await readFile6(p, "utf8");
     return JSON.parse(result);
   } catch (e) {
     return null;
@@ -2018,7 +2130,7 @@ var get2 = async (repoPath, key) => {
 };
 var set2 = async (repoPath, key, result) => {
   const p = getCachePath2(repoPath, key);
-  await mkdir4(path9.dirname(p), { recursive: true });
+  await mkdir4(path10.dirname(p), { recursive: true });
   await writeFile7(p, JSON.stringify(result));
 };
 var getUnsupportedCachePath = (repoDir) => {
@@ -2065,7 +2177,7 @@ var markAdaptorAsUnsupported = async (adaptorSpecifier, repoDir) => {
   const cachePath = getUnsupportedCachePath(repoDir);
   let cache = {};
   try {
-    const cacheContent = await readFile5(cachePath, "utf8");
+    const cacheContent = await readFile6(cachePath, "utf8");
     cache = JSON.parse(cacheContent);
   } catch (error) {
   }
@@ -2077,7 +2189,7 @@ var markAdaptorAsUnsupported = async (adaptorSpecifier, repoDir) => {
       majorMinor: parsed.majorMinor,
       timestamp: Date.now()
     };
-    await mkdir4(path9.dirname(cachePath), { recursive: true });
+    await mkdir4(path10.dirname(cachePath), { recursive: true });
     await writeFile7(cachePath, JSON.stringify(cache, null, 2));
   }
 };
@@ -2116,8 +2228,8 @@ var getAdaptorPath = async (adaptor, logger, repoDir) => {
   return adaptorPath;
 };
 var shouldAutoinstall = (adaptor) => adaptor?.length > 0 && !adaptor.startsWith("/") && !adaptor.includes("=");
-var metadataHandler = async (options6, logger) => {
-  const { repoDir, adaptors, keepUnsupported } = options6;
+var metadataHandler = async (options7, logger) => {
+  const { repoDir, adaptors, keepUnsupported } = options7;
   let adaptor = adaptors[0];
   if (await isAdaptorUnsupported(adaptor, repoDir)) {
     logger.info(
@@ -2126,7 +2238,7 @@ var metadataHandler = async (options6, logger) => {
     logger.error("No metadata helper found");
     process.exit(1);
   }
-  const state = await load_state_default({}, options6, logger);
+  const state = await load_state_default({}, options7, logger);
   logger.success(`Generating metadata`);
   logger.info("config:", state);
   const config2 = state.configuration;
@@ -2139,7 +2251,7 @@ var metadataHandler = async (options6, logger) => {
     logger.print(getCachePath2(repoDir, id));
   };
   const id = generateKey(config2, adaptor);
-  if (!options6.force) {
+  if (!options7.force) {
     logger.debug("config hash: ", id);
     const cached = await get2(repoDir, id);
     if (cached) {
@@ -2157,7 +2269,7 @@ var metadataHandler = async (options6, logger) => {
       wasAutoInstalled = true;
       adaptor = autoinstallResult[0];
     }
-    const adaptorPath = await getAdaptorPath(adaptor, logger, options6.repoDir);
+    const adaptorPath = await getAdaptorPath(adaptor, logger, options7.repoDir);
     if (!adaptorPath) {
       throw new Error(`Could not resolve adaptor path for ${adaptor}`);
     }
@@ -2199,20 +2311,16 @@ var metadataHandler = async (options6, logger) => {
 var handler_default9 = metadataHandler;
 
 // src/pull/handler.ts
-import path12 from "path";
+import path14 from "path";
 import fs5 from "node:fs/promises";
 import {
   getConfig as getConfig2,
-  getProject as getProject2,
+  getProject,
   getSpec,
   getStateFromProjectPayload,
   syncRemoteSpec
 } from "@openfn/deploy";
 
-// src/projects/fetch.ts
-import path10 from "node:path";
-import Project3, { Workspace } from "@openfn/project";
-
 // src/util/command-builders.ts
 import c2 from "chalk";
 var expandYargs = (y) => {
@@ -2222,13 +2330,17 @@ var expandYargs = (y) => {
   return y;
 };
 function build(opts, yargs) {
-  return opts.reduce(
-    (_y, o) => yargs.option(o.name, expandYargs(o.yargs)),
-    yargs
-  );
+  return opts.reduce((_y, o) => {
+    if (!o?.name) {
+      console.error(`ERROR: INVALID COMMAND OPTION PASSED`, o);
+      console.error("Check the options passed to the command builder");
+      throw new Error("Invalid command");
+    }
+    return yargs.option(o.name, expandYargs(o.yargs));
+  }, yargs);
 }
-var ensure = (command6, opts) => (yargs) => {
-  yargs.command = command6;
+var ensure = (command7, opts) => (yargs) => {
+  yargs.command = command7;
   opts.filter((opt) => opt.ensure).forEach((opt) => {
     try {
       opt.ensure(yargs);
@@ -2236,7 +2348,7 @@ var ensure = (command6, opts) => (yargs) => {
       console.log(e);
       console.error(
         c2.red(`
-Error parsing command arguments: ${command6}.${opt.name}
+Error parsing command arguments: ${command7}.${opt.name}
 `)
       );
       console.error(c2.red("Aborting"));
@@ -2245,18 +2357,19 @@ Error parsing command arguments: ${command6}.${opt.name}
     }
   });
 };
-var override = (command6, yargs) => {
+var override = (command7, yargs) => {
   return {
-    ...command6,
+    ...command7,
     yargs: {
-      ...command6.yargs || {},
+      ...command7.yargs || {},
       ...yargs
     }
   };
 };
 
-// src/options.ts
-import nodePath from "node:path";
+// src/projects/fetch.ts
+import path12 from "node:path";
+import Project3, { Workspace } from "@openfn/project";
 
 // src/util/ensure-log-opts.ts
 var defaultLoggerOptions = {
@@ -2315,49 +2428,17 @@ var ensureLogOpts = (opts) => {
 };
 var ensure_log_opts_default = ensureLogOpts;
 
-// src/util/get-cli-option-object.ts
-function getCLIOptionObject(arg) {
-  if (isObject(arg)) {
-    return arg;
-  } else if (typeof arg === "string") {
-    try {
-      const p = JSON.parse(arg);
-      if (isObject(p))
-        return p;
-    } catch (e) {
-    }
-    return Object.fromEntries(
-      arg.split(",").map((pair) => {
-        const [k, v] = pair.split("=");
-        return [k.trim(), v.trim()];
-      })
-    );
-  }
-}
-function isObject(arg) {
-  return typeof arg === "object" && arg !== null && !Array.isArray(arg);
-}
-
 // src/options.ts
-var setDefaultValue = (opts, key, value) => {
-  const v = opts[key];
-  if (isNaN(v) && !v) {
-    opts[key] = value;
-  }
-};
-var apikey = {
+var apiKey = {
   name: "apikey",
   yargs: {
-    alias: ["key", "pat", "token"],
-    description: "[beta only] API Key, Personal Access Token (Pat), or other access token"
-  }
-};
-var configPath = {
-  name: "config",
-  yargs: {
-    alias: ["c", "config-path"],
-    description: "The location of your config file",
-    default: "./.config.json"
+    alias: ["pat", "token", "api-key"],
+    description: "API Key, Personal Access Token (PAT), or other access token from Lightning"
+  },
+  ensure: (opts) => {
+    if (!opts.apikey) {
+      opts.apiKey = process.env.OPENFN_API_KEY;
+    }
   }
 };
 var endpoint = {
@@ -2367,12 +2448,6 @@ var endpoint = {
     description: "[beta only] URL to Lightning endpoint"
   }
 };
-var env = {
-  name: "env",
-  yargs: {
-    description: "[beta only] Environment name (eg staging, prod, branch)"
-  }
-};
 var force = {
   name: "force",
   yargs: {
@@ -2382,23 +2457,6 @@ var force = {
     default: false
   }
 };
-var getBaseDir = (opts) => {
-  const basePath = opts.path ?? ".";
-  if (/\.(jso?n?|ya?ml)$/.test(basePath)) {
-    return nodePath.dirname(basePath);
-  }
-  return basePath;
-};
-var projectId = {
-  name: "project-id",
-  yargs: {
-    description: "The id or UUID of an openfn project",
-    string: true
-  },
-  ensure: (opts) => {
-    return opts.projectName;
-  }
-};
 var log = {
   name: "log",
   yargs: {
@@ -2417,26 +2475,18 @@ var logJson = {
     boolean: true
   }
 };
-var outputPath = {
-  name: "output-path",
+var projectPath = {
+  name: "project-path",
   yargs: {
-    alias: "o",
-    description: "Path to the output file"
-  },
-  ensure: (opts) => {
-    if (/^(compile|apollo)$/.test(opts.command)) {
-      if (opts.outputPath) {
-        delete opts.outputStdout;
-      }
-    } else {
-      if (opts.outputStdout) {
-        delete opts.outputPath;
-      } else {
-        const base = getBaseDir(opts);
-        setDefaultValue(opts, "outputPath", nodePath.join(base, "output.json"));
-      }
-    }
-    delete opts.o;
+    string: true,
+    alias: ["p"],
+    description: "The location of your project.yaml file"
+  }
+};
+var path11 = {
+  name: "path",
+  yargs: {
+    description: "Path"
   }
 };
 var snapshots = {
@@ -2446,16 +2496,6 @@ var snapshots = {
     array: true
   }
 };
-var statePath = {
-  name: "state-path",
-  yargs: {
-    alias: ["s"],
-    description: "Path to the state file"
-  },
-  ensure: (opts) => {
-    delete opts.s;
-  }
-};
 var timeout = {
   name: "timeout",
   yargs: {
@@ -2472,6 +2512,44 @@ var workflow = {
     description: "Name of the workflow to execute"
   }
 };
+
+// src/util/get-cli-option-object.ts
+function getCLIOptionObject(arg) {
+  if (isObject(arg)) {
+    return arg;
+  } else if (typeof arg === "string") {
+    try {
+      const p = JSON.parse(arg);
+      if (isObject(p))
+        return p;
+    } catch (e) {
+    }
+    return Object.fromEntries(
+      arg.split(",").map((pair) => {
+        const [k, v] = pair.split("=");
+        return [k.trim(), v.trim()];
+      })
+    );
+  }
+}
+function isObject(arg) {
+  return typeof arg === "object" && arg !== null && !Array.isArray(arg);
+}
+
+// src/projects/options.ts
+var env = {
+  name: "env",
+  yargs: {
+    description: "Environment name (eg staging, prod, branch)",
+    hidden: true
+  }
+};
+var alias = {
+  name: "alias",
+  yargs: {
+    description: "Environment name (eg staging, prod, branch)"
+  }
+};
 var removeUnmapped = {
   name: "remove-unmapped",
   yargs: {
@@ -2487,6 +2565,14 @@ var workflowMappings = {
     description: "A manual object mapping of which workflows in source and target should be matched for a merge."
   }
 };
+var outputPath = {
+  name: "output-path",
+  yargs: {
+    alias: ["output"],
+    type: "string",
+    description: "Path to output the fetched project to"
+  }
+};
 var workspace = {
   name: "workspace",
   yargs: {
@@ -2498,129 +2584,228 @@ var workspace = {
     if (!ws) {
       opts.workspace = process.cwd();
     } else {
-      opts.workspace = nodePath.resolve(ws);
+      opts.workspace = resolve_path_default(ws);
     }
   }
 };
 
 // src/projects/fetch.ts
 var options = [
-  apikey,
-  configPath,
+  alias,
+  apiKey,
   endpoint,
-  env,
   log,
-  override(outputPath, {
-    description: "Path to output the fetched project to"
-  }),
   logJson,
-  workspace,
   snapshots,
-  statePath,
+  // TODO need to add support for this
   override(force, {
     description: "Overwrite local file contents with the fetched contents"
-  })
+  }),
+  outputPath,
+  env,
+  workspace
 ];
 var command = {
-  command: "fetch [projectId]",
-  describe: `Fetch a project's state and spec from a Lightning Instance to the local state file without expanding to the filesystem.`,
-  builder: (yargs) => build(options, yargs).positional("projectId", {
-    describe: "The id of the project that should be fetched, should be a UUID",
-    demandOption: true
+  command: "fetch [project]",
+  describe: `Download the latest version of a project from a lightning server (does not expand the project, use checkout)`,
+  builder: (yargs) => build(options, yargs).positional("project", {
+    describe: "The id, alias or UUID of the project to fetch. If not set, will default to the active project"
   }).example(
     "fetch 57862287-23e6-4650-8d79-e1dd88b24b1c",
     "Fetch an updated copy of a the above spec and state from a Lightning Instance"
   ),
   handler: ensure("project-fetch", options)
 };
-var handler2 = async (options6, logger) => {
-  const workspacePath = path10.resolve(options6.workspace ?? process.cwd());
-  const workspace2 = new Workspace(workspacePath);
-  const { projectId: projectId2, outputPath: outputPath2 } = options6;
-  const config2 = loadAppAuthConfig(options6, logger);
-  const { data } = await getProject(logger, config2, projectId2);
-  const project = await Project3.from(
-    "state",
-    data,
-    {
-      endpoint: config2.endpoint,
-      env: options6.env || "project"
-    },
-    workspace2.getConfig()
+var printProjectName = (project) => `${project.qname} (${project.id})`;
+var handler2 = async (options7, logger) => {
+  const workspacePath = options7.workspace ?? process.cwd();
+  logger.debug("Using workspace at", workspacePath);
+  const workspace2 = new Workspace(workspacePath, logger, false);
+  const { outputPath: outputPath2 } = options7;
+  const localTargetProject = await resolveOutputProject(
+    workspace2,
+    options7,
+    logger
   );
-  const outputRoot = path10.resolve(outputPath2 || workspacePath);
-  const projectFileName = project.getIdentifier();
-  const projectsDir = project.config.dirs.projects ?? ".projects";
-  const finalOutputPath = outputPath2 ?? `${outputRoot}/${projectsDir}/${projectFileName}`;
+  const remoteProject = await fetchRemoteProject(workspace2, options7, logger);
+  ensureTargetCompatible(options7, remoteProject, localTargetProject);
+  const outputRoot = resolve_path_default(outputPath2 || workspacePath);
+  const projectsDir = remoteProject?.config.dirs.projects ?? ".projects";
+  const finalOutputPath = outputPath2 ?? `${outputRoot}/${projectsDir}/${remoteProject.qname}`;
   let format = void 0;
   if (outputPath2) {
-    const ext = path10.extname(outputPath2).substring(1);
+    const ext = path12.extname(outputPath2).substring(1);
     if (ext.length) {
       format = ext;
     }
+    if (options7.alias) {
+      logger.warn(
+        `WARNING: alias "${options7.alias}" was set, but will be ignored as output path was provided`
+      );
+    }
   }
-  const finalOutput = await serialize(
-    project,
-    finalOutputPath,
-    format,
-    true
-    // dry run - this won't trigger an actual write!
+  await serialize(remoteProject, finalOutputPath, format);
+  logger.success(
+    `Fetched project file to ${finalOutputPath}.${format ?? "yaml"}`
   );
-  let current = null;
-  try {
-    current = await Project3.from("path", finalOutput);
-  } catch (e) {
+  return remoteProject;
+};
+async function resolveOutputProject(workspace2, options7, logger) {
+  logger.debug("Checking for local copy of project...");
+  if (options7.outputPath) {
+    try {
+      const customProject = await Project3.from("path", options7.outputPath);
+      logger.debug(
+        `Found existing local project ${printProjectName(customProject)} at`,
+        options7.outputPath
+      );
+      return customProject;
+    } catch (e) {
+      logger.debug("No project found at", options7.outputPath);
+    }
+  }
+  if (options7.alias) {
+    const aliasProject = workspace2.get(options7.alias);
+    if (aliasProject) {
+      logger.debug(
+        `Found local project from alias:`,
+        printProjectName(aliasProject)
+      );
+      return aliasProject;
+    } else {
+      logger.debug(`No local project found with alias ${options7.alias}`);
+    }
+  }
+  const project = workspace2.get(options7.project);
+  if (project) {
+    logger.debug(
+      `Found local project from identifier:`,
+      printProjectName(project)
+    );
+    return project;
+  } else {
+    logger.debug(
+      `No local project found matching identifier: `,
+      options7.project
+    );
   }
-  const hasAnyHistory = project.workflows.find(
-    (w) => w.workflow.history?.length
+}
+async function fetchRemoteProject(workspace2, options7, logger) {
+  logger.debug(`Fetching latest project data from app`);
+  const config2 = loadAppAuthConfig(options7, logger);
+  let projectUUID = options7.project;
+  const localProject = workspace2.get(options7.project);
+  if (localProject?.openfn?.uuid && localProject.openfn.uuid !== options7.project) {
+    projectUUID = localProject.openfn.uuid;
+    logger.debug(
+      `Resolved ${options7.project} to UUID ${projectUUID} from local project ${printProjectName(
+        localProject
+      )}}`
+    );
+  }
+  const projectEndpoint = localProject?.openfn?.endpoint ?? config2.endpoint;
+  const { data } = await fetchProject(
+    projectEndpoint,
+    config2.apiKey,
+    projectUUID,
+    logger
+  );
+  const project = await Project3.from(
+    "state",
+    data,
+    {
+      endpoint: projectEndpoint
+    },
+    {
+      ...workspace2.getConfig(),
+      alias: options7.alias ?? localProject?.alias ?? "main"
+    }
+  );
+  logger.debug(
+    `Loaded remote project ${project.openfn.uuid} with id ${project.id} and alias ${project.alias}`
   );
-  const skipVersionCheck = options6.force || // The user forced the checkout
-  !current || // there is no project on disk
-  !hasAnyHistory;
-  if (!skipVersionCheck && !project.canMergeInto(current)) {
-    throw new Error("Error! An incompatible project exists at this location");
-  }
-  await serialize(project, finalOutputPath, format);
-  logger.success(`Fetched project file to ${finalOutput}`);
   return project;
-};
+}
+function ensureTargetCompatible(options7, remoteProject, localProject) {
+  if (localProject) {
+    if (!options7.force && localProject.uuid != remoteProject.uuid) {
+      const error = new Error("PROJECT_EXISTS");
+      error.message = "A project with a different UUID exists at this location";
+      error.fix = `You have tried to fetch a remote project into a local project with a different UUID
+
+Try adding an alias to rename the new project:
+
+      openfn fetch ${options7.project} --alias ${remoteProject.id}
+
+To ignore this error and override the local file, pass --force (-f)
+
+    openfn fetch ${options7.project} --force
+`;
+      error.fetched_project = {
+        uuid: remoteProject.uuid,
+        id: remoteProject.id,
+        alias: remoteProject.alias
+      };
+      error.local_project = {
+        uuid: localProject.uuid,
+        id: localProject.id,
+        alias: localProject.alias
+      };
+      delete error.stack;
+      throw error;
+    }
+    const hasAnyHistory = remoteProject.workflows.find(
+      (w) => w.workflow.history?.length
+    );
+    const skipVersionCheck = options7.force || // The user forced the checkout
+    !hasAnyHistory;
+    if (!skipVersionCheck && !remoteProject.canMergeInto(localProject)) {
+      throw new Error("Error! An incompatible project exists at this location");
+    }
+  }
+}
 
 // src/projects/checkout.ts
 import Project4, { Workspace as Workspace2 } from "@openfn/project";
-import path11 from "path";
+import path13 from "path";
 import fs4 from "fs";
 import { rimraf } from "rimraf";
-var options2 = [projectId, workspace, log];
+var options2 = [log, workspace];
 var command2 = {
-  command: "checkout <project-id>",
+  command: "checkout <project>",
   describe: "Switch to a different OpenFn project in the same workspace",
   handler: ensure("project-checkout", options2),
-  builder: (yargs) => build(options2, yargs)
+  builder: (yargs) => build(options2, yargs).positional("project", {
+    describe: "The id, alias or UUID of the project to chcekout",
+    demandOption: true
+  })
 };
-var handler3 = async (options6, logger) => {
-  const projectId2 = options6.projectId;
-  const workspacePath = options6.workspace ?? process.cwd();
+var handler3 = async (options7, logger) => {
+  const projectIdentifier = options7.project;
+  const workspacePath = options7.workspace ?? process.cwd();
   const workspace2 = new Workspace2(workspacePath, logger);
   const { project: _, ...config2 } = workspace2.getConfig();
   let switchProject;
-  if (/\.(yaml|json)$/.test(projectId2)) {
-    const filePath = projectId2.startsWith("/") ? projectId2 : path11.join(workspacePath, projectId2);
+  if (/\.(yaml|json)$/.test(projectIdentifier)) {
+    const filePath = projectIdentifier.startsWith("/") ? projectIdentifier : path13.join(workspacePath, projectIdentifier);
     logger.debug("Loading project from path ", filePath);
     switchProject = await Project4.from("path", filePath, config2);
   } else {
-    switchProject = workspace2.get(projectId2);
+    switchProject = workspace2.get(projectIdentifier);
   }
   if (!switchProject) {
-    throw new Error(`Project with id ${projectId2} not found in the workspace`);
+    throw new Error(
+      `Project with id ${projectIdentifier} not found in the workspace`
+    );
   }
-  await rimraf(path11.join(workspacePath, config2.workflowRoot ?? "workflows"));
+  await rimraf(path13.join(workspacePath, config2.workflowRoot ?? "workflows"));
   const files = switchProject.serialize("fs");
   for (const f in files) {
     if (files[f]) {
-      fs4.mkdirSync(path11.join(workspacePath, path11.dirname(f)), {
+      fs4.mkdirSync(path13.join(workspacePath, path13.dirname(f)), {
         recursive: true
       });
-      fs4.writeFileSync(path11.join(workspacePath, f), files[f]);
+      fs4.writeFileSync(path13.join(workspacePath, f), files[f]);
     } else {
       logger.warn("WARNING! No content for file", f);
     }
@@ -2629,27 +2814,48 @@ var handler3 = async (options6, logger) => {
 };
 
 // src/projects/pull.ts
-async function handler4(options6, logger) {
-  const project = await handler2(options6, logger);
+var options3 = [
+  alias,
+  env,
+  workspace,
+  apiKey,
+  endpoint,
+  log,
+  override(path11, {
+    description: "path to output the project to"
+  }),
+  logJson,
+  projectPath,
+  snapshots,
+  path11,
+  force
+];
+var command3 = {
+  command: "pull [project]",
+  describe: `Pull a project from a Lightning Instance and expand to the file system (ie fetch + checkout)`,
+  builder: (yargs) => build(options3, yargs).positional("project", {
+    describe: "The UUID, local id or local alias of the project to pull"
+  }).example(
+    "pull 57862287-23e6-4650-8d79-e1dd88b24b1c",
+    "Pull project with a UUID from a lightning instance"
+  ),
+  handler: ensure("project-pull", options3)
+};
+async function handler4(options7, logger) {
+  await handler2(options7, logger);
   logger.success(`Downloaded latest project version`);
-  await handler3(
-    {
-      ...options6,
-      projectId: project.id
-    },
-    logger
-  );
+  await handler3(options7, logger);
   logger.success(`Checked out project locally`);
 }
 var pull_default = handler4;
 
 // src/pull/handler.ts
-async function pullHandler(options6, logger) {
-  if (options6.beta) {
-    return pull_default(options6, logger);
+async function pullHandler(options7, logger) {
+  if (options7.beta) {
+    return pull_default(options7, logger);
   }
   try {
-    const config2 = mergeOverrides2(await getConfig2(options6.configPath), options6);
+    const config2 = mergeOverrides2(await getConfig2(options7.configPath), options7);
     if (process.env["OPENFN_API_KEY"]) {
       logger.info("Using OPENFN_API_KEY environment variable");
       config2.apiKey = process.env["OPENFN_API_KEY"];
@@ -2661,10 +2867,10 @@ async function pullHandler(options6, logger) {
     logger.always(
       "Downloading existing project state (as JSON) from the server."
     );
-    const { data: project } = await getProject2(
+    const { data: project } = await getProject(
       config2,
-      options6.projectId,
-      options6.snapshots
+      options7.projectId,
+      options7.snapshots
     );
     if (!project) {
       logger.error("ERROR: Project not found.");
@@ -2677,8 +2883,8 @@ async function pullHandler(options6, logger) {
     const state = getStateFromProjectPayload(project);
     logger.always("Downloading the project spec (as YAML) from the server.");
     const queryParams = new URLSearchParams();
-    queryParams.append("id", options6.projectId);
-    options6.snapshots?.forEach(
+    queryParams.append("id", options7.projectId);
+    options7.snapshots?.forEach(
       (snapshot) => queryParams.append("snapshots[]", snapshot)
     );
     const url2 = new URL(
@@ -2700,7 +2906,7 @@ async function pullHandler(options6, logger) {
       process.exitCode = 1;
       process.exit(1);
     }
-    const resolvedPath = path12.resolve(config2.specPath);
+    const resolvedPath = path14.resolve(config2.specPath);
     logger.debug("reading spec from", resolvedPath);
     const updatedSpec = await syncRemoteSpec(
       await res.text(),
@@ -2709,7 +2915,7 @@ async function pullHandler(options6, logger) {
       logger
     );
     await fs5.writeFile(
-      path12.resolve(config2.statePath),
+      path14.resolve(config2.statePath),
       JSON.stringify(state, null, 2)
     );
     await fs5.writeFile(resolvedPath, updatedSpec);
@@ -2727,13 +2933,13 @@ async function pullHandler(options6, logger) {
     throw error;
   }
 }
-function mergeOverrides2(config2, options6) {
+function mergeOverrides2(config2, options7) {
   return {
     ...config2,
     apiKey: pickFirst2(process.env["OPENFN_API_KEY"], config2.apiKey),
     endpoint: pickFirst2(process.env["OPENFN_ENDPOINT"], config2.endpoint),
-    configPath: options6.configPath,
-    requireConfirmation: pickFirst2(options6.confirm, config2.requireConfirmation)
+    configPath: options7.configPath,
+    requireConfirmation: pickFirst2(options7.confirm, config2.requireConfirmation)
   };
 }
 function pickFirst2(...args) {
@@ -2748,35 +2954,36 @@ __export(handler_exports, {
   fetch: () => handler2,
   list: () => handler5,
   merge: () => handler7,
+  pull: () => handler4,
   version: () => handler6
 });
 
 // src/projects/list.ts
 import { Workspace as Workspace3 } from "@openfn/project";
-var options3 = [log, workspace];
-var command3 = {
+var options4 = [log, workspace];
+var command4 = {
   command: "list [project-path]",
   describe: "List all the openfn projects available in the current directory",
   aliases: ["project", "$0"],
-  handler: ensure("project-list", options3),
-  builder: (yargs) => build(options3, yargs)
+  handler: ensure("project-list", options4),
+  builder: (yargs) => build(options4, yargs)
 };
-var handler5 = async (options6, logger) => {
+var handler5 = async (options7, logger) => {
   logger.info("Searching for projects in workspace at:");
-  logger.info(" ", options6.workspace);
+  logger.info(" ", options7.workspace);
   logger.break();
-  const workspace2 = new Workspace3(options6.workspace);
+  const workspace2 = new Workspace3(options7.workspace);
   if (!workspace2.valid) {
     throw new Error("No OpenFn projects found");
   }
   logger.always(`Available openfn projects
 
-${workspace2.list().map((p) => describeProject(p, p.id === workspace2.activeProjectId)).join("\n\n")}
+${workspace2.list().map((p) => describeProject(p, p === workspace2.getActiveProject())).join("\n\n")}
     `);
 };
 function describeProject(project, active = false) {
   const uuid = project.openfn?.uuid;
-  return `${project.id} ${active ? "(active)" : ""}
+  return `${project.alias || "(no alias)"} | ${project.id} ${active ? "(active)" : ""}
   ${uuid || "<project-id>"}
   workflows:
 ${project.workflows.map((w) => "    - " + w.id).join("\n")}`;
@@ -2784,25 +2991,25 @@ ${project.workflows.map((w) => "    - " + w.id).join("\n")}`;
 
 // src/projects/version.ts
 import { Workspace as Workspace4 } from "@openfn/project";
-var options4 = [workflow, workspace, workflowMappings];
-var command4 = {
+var options5 = [workflow, workspace, workflowMappings];
+var command5 = {
   command: "version [workflow]",
   describe: "Returns the version hash of a given workflow in a workspace",
-  handler: ensure("project-version", options4),
-  builder: (yargs) => build(options4, yargs)
+  handler: ensure("project-version", options5),
+  builder: (yargs) => build(options5, yargs)
 };
-var handler6 = async (options6, logger) => {
-  const workspace2 = new Workspace4(options6.workspace);
+var handler6 = async (options7, logger) => {
+  const workspace2 = new Workspace4(options7.workspace);
   if (!workspace2.valid) {
     logger.error("Command was run in an invalid openfn workspace");
     return;
   }
   const output = /* @__PURE__ */ new Map();
   const activeProject = workspace2.getActiveProject();
-  if (options6.workflow) {
-    const workflow2 = activeProject?.getWorkflow(options6.workflow);
+  if (options7.workflow) {
+    const workflow2 = activeProject?.getWorkflow(options7.workflow);
     if (!workflow2) {
-      logger.error(`No workflow found with id ${options6.workflow}`);
+      logger.error(`No workflow found with id ${options7.workflow}`);
       return;
     }
     output.set(workflow2.name || workflow2.id, workflow2.getVersionHash());
@@ -2816,7 +3023,7 @@ var handler6 = async (options6, logger) => {
     return;
   }
   let final;
-  if (options6.json) {
+  if (options7.json) {
     final = JSON.stringify(Object.fromEntries(output), void 0, 2);
   } else {
     final = Array.from(output.entries()).map(([key, value]) => key + "\n" + value).join("\n\n");
@@ -2828,16 +3035,16 @@ ${final}`);
 
 // src/projects/merge.ts
 import Project6, { Workspace as Workspace5 } from "@openfn/project";
-import path13 from "node:path";
+import path15 from "node:path";
 import fs6 from "node:fs/promises";
-var options5 = [
-  projectId,
+var options6 = [
   removeUnmapped,
   workflowMappings,
-  log,
   workspace,
+  log,
   // custom output because we don't want defaults or anything
   {
+    // TODO presumably if we do this we don't also checkout?
     name: "output-path",
     yargs: {
       alias: "o",
@@ -2855,22 +3062,22 @@ var options5 = [
     description: "Force a merge even when workflows are incompatible"
   })
 ];
-var command5 = {
-  command: "merge <project-id>",
-  describe: "Merges the specified project into the currently checked out project",
-  handler: ensure("project-merge", options5),
-  builder: (yargs) => build(options5, yargs)
-};
-var handler7 = async (options6, logger) => {
-  const commandPath = options6.workspace;
-  const workspace2 = new Workspace5(commandPath);
+var command6 = {
+  command: "merge <project>",
+  describe: "Merges the specified project (by UUID, id or alias) into the currently checked out project",
+  handler: ensure("project-merge", options6),
+  builder: (yargs) => build(options6, yargs)
+};
+var handler7 = async (options7, logger) => {
+  const workspacePath = options7.workspace;
+  const workspace2 = new Workspace5(workspacePath);
   if (!workspace2.valid) {
     logger.error("Command was run in an invalid openfn workspace");
     return;
   }
   let targetProject;
-  if (options6.base) {
-    const basePath = path13.resolve(options6.base);
+  if (options7.base) {
+    const basePath = path15.resolve(options7.base);
     logger.debug("Loading target project from path", basePath);
     targetProject = await Project6.from("path", basePath);
   } else {
@@ -2881,17 +3088,22 @@ var handler7 = async (options6, logger) => {
     }
     logger.debug(`Loading target project from workspace (${targetProject.id})`);
   }
+  const sourceProjectIdentifier = options7.project;
   let sourceProject;
-  if (/\.(yaml|json)$/.test(options6.projectId)) {
-    const filePath = path13.join(commandPath, options6.projectId);
+  if (/\.(ya?ml|json)$/.test(sourceProjectIdentifier)) {
+    const filePath = path15.join(workspacePath, sourceProjectIdentifier);
     logger.debug("Loading source project from path ", filePath);
     sourceProject = await Project6.from("path", filePath);
   } else {
-    logger.debug(`Loading source project from workspace ${options6.projectId}`);
-    sourceProject = workspace2.get(options6.projectId);
+    logger.debug(
+      `Loading source project from workspace ${sourceProjectIdentifier}`
+    );
+    sourceProject = workspace2.get(sourceProjectIdentifier);
   }
   if (!sourceProject) {
-    logger.error(`Project "${options6.projectId}" not found in the workspace`);
+    logger.error(
+      `Project "${sourceProjectIdentifier}" not found in the workspace`
+    );
     return;
   }
   if (targetProject.id === sourceProject.id) {
@@ -2902,20 +3114,20 @@ var handler7 = async (options6, logger) => {
     logger.error("The checked out project has no id");
     return;
   }
-  const finalPath = options6.outputPath ?? workspace2.getProjectPath(targetProject.id);
+  const finalPath = options7.outputPath ?? workspace2.getProjectPath(targetProject.id);
   if (!finalPath) {
     logger.error("Path to checked out project not found.");
     return;
   }
   const final = Project6.merge(sourceProject, targetProject, {
-    removeUnmapped: options6.removeUnmapped,
-    workflowMappings: options6.workflowMappings,
-    force: options6.force
+    removeUnmapped: options7.removeUnmapped,
+    workflowMappings: options7.workflowMappings,
+    force: options7.force
   });
   let outputFormat = workspace2.config.formats.project;
-  if (options6.outputPath?.endsWith(".json")) {
+  if (options7.outputPath?.endsWith(".json")) {
     outputFormat = "json";
-  } else if (options6.outputPath?.endsWith(".yaml")) {
+  } else if (options7.outputPath?.endsWith(".yaml")) {
     outputFormat = "yaml";
   }
   let finalState = final.serialize("state", {
@@ -2929,10 +3141,9 @@ var handler7 = async (options6, logger) => {
   logger.info("Checking out merged project to filesystem");
   await handler3(
     {
-      command: "project-checkout",
-      workspace: commandPath,
-      projectId: options6.outputPath ? finalPath : final.id,
-      log: options6.log
+      workspace: workspacePath,
+      project: options7.outputPath ? finalPath : final.id,
+      log: options7.log
     },
     logger
   );
@@ -2943,7 +3154,7 @@ var handler7 = async (options6, logger) => {
 
 // src/util/print-versions.ts
 import { readFileSync as readFileSync2 } from "node:fs";
-import path14 from "node:path";
+import path16 from "node:path";
 import url from "node:url";
 import { getNameAndVersion as getNameAndVersion7 } from "@openfn/runtime";
 import { mainSymbols } from "figures";
@@ -2955,15 +3166,15 @@ var { triangleRightSmall: t } = mainSymbols;
 var loadVersionFromPath = (adaptorPath) => {
   try {
     const pkg = JSON.parse(
-      readFileSync2(path14.resolve(adaptorPath, "package.json"), "utf8")
+      readFileSync2(path16.resolve(adaptorPath, "package.json"), "utf8")
     );
     return pkg.version;
   } catch (e) {
     return "unknown";
   }
 };
-var printVersions = async (logger, options6 = {}, includeComponents = false) => {
-  const { adaptors, logJson: logJson2 } = options6;
+var printVersions = async (logger, options7 = {}, includeComponents = false) => {
+  const { adaptors, logJson: logJson2 } = options7;
   let longestAdaptorName = "";
   const adaptorList = [];
   adaptors?.forEach((adaptor) => {
@@ -2973,7 +3184,7 @@ var printVersions = async (logger, options6 = {}, includeComponents = false) =>
       const [namePart, pathPart] = adaptor.split("=");
       adaptorVersion = loadVersionFromPath(pathPart);
       adaptorName = getNameAndVersion7(namePart).name;
-    } else if (options6.monorepoPath) {
+    } else if (options7.monorepoPath) {
       adaptorName = getNameAndVersion7(adaptor).name;
       adaptorVersion = "monorepo";
     } else {
@@ -2990,7 +3201,7 @@ var printVersions = async (logger, options6 = {}, includeComponents = false) =>
     ...[NODE, CLI2, RUNTIME2, COMPILER2, longestAdaptorName].map((s) => s.length)
   );
   const prefix = (str) => `         ${t} ${str.padEnd(longest + 4, " ")}`;
-  const dirname3 = path14.dirname(url.fileURLToPath(import.meta.url));
+  const dirname3 = path16.dirname(url.fileURLToPath(import.meta.url));
   const pkg = JSON.parse(readFileSync2(`${dirname3}/../../package.json`, "utf8"));
   const { version, dependencies } = pkg;
   const compilerVersion = dependencies["@openfn/compiler"];
@@ -3071,6 +3282,7 @@ var handlers = {
   ["repo-install"]: install,
   ["repo-pwd"]: pwd,
   ["repo-list"]: list,
+  ["project-pull"]: handler4,
   ["project-list"]: handler5,
   ["project-version"]: handler6,
   ["project-merge"]: handler7,
@@ -3078,13 +3290,13 @@ var handlers = {
   ["project-fetch"]: handler2,
   version: async (opts, logger) => print_versions_default(logger, opts, true)
 };
-var parse = async (options6, log2) => {
-  const logger = log2 || logger_default(CLI, options6);
-  if (options6.command === "execute" || options6.command === "test") {
-    await print_versions_default(logger, options6);
+var parse = async (options7, log2) => {
+  const logger = log2 || logger_default(CLI, options7);
+  if (options7.command === "execute" || options7.command === "test") {
+    await print_versions_default(logger, options7);
   }
   report(logger);
-  const { monorepoPath } = options6;
+  const { monorepoPath } = options7;
   if (monorepoPath) {
     if (monorepoPath === "ERR") {
       logger.error(
@@ -3095,19 +3307,19 @@ var parse = async (options6, log2) => {
     }
     await validateMonoRepo(monorepoPath, logger);
     logger.success(`Loading adaptors from monorepo at ${monorepoPath}`);
-    options6.adaptors = map_adaptors_to_monorepo_default(
+    options7.adaptors = map_adaptors_to_monorepo_default(
       monorepoPath,
-      options6.adaptors,
+      options7.adaptors,
       logger
     );
   }
-  const handler8 = handlers[options6.command];
+  const handler8 = handlers[options7.command];
   if (!handler8) {
-    logger.error(`Unrecognised command: ${options6.command}`);
+    logger.error(`Unrecognised command: ${options7.command}`);
     process.exit(1);
   }
   try {
-    return await handler8(options6, logger);
+    return await handler8(options7, logger);
   } catch (e) {
     if (!process.exitCode) {
       process.exitCode = e.exitCode || 1;