Codefresh CLI

Common errors

• codefresh: command not found

  cause The Codefresh CLI is not installed globally or is not available in your system's PATH.
  fix Install the CLI globally using npm: `npm install -g codefresh`.

• Error: API key is missing or invalid. Please generate one from your Codefresh account settings.

  cause The provided API key during `codefresh auth create-context` is incorrect, expired, or was not set.
  fix Generate a new API key from your Codefresh account settings and ensure it is correctly provided: `codefresh auth create-context --api-key {{YOUR_API_KEY}}`.

• Error: Minimum Node.js version 24.0.0 is required. Detected version X.Y.Z

  cause You are attempting to run the Codefresh CLI with an unsupported, older version of Node.js.
  fix Upgrade your Node.js installation to version 24.0.0 or higher. Tools like `nvm` (Node Version Manager) can help manage multiple Node.js versions.

• Cannot find module 'codefresh' or 'codefresh/lib/some_module'

  cause Attempting to `import` or `require` the `codefresh` package as a regular JavaScript library.
  fix The `codefresh` package is a CLI tool. Do not import it directly. Instead, execute its commands via `child_process.spawn` or `execa` for programmatic interaction.

Warnings

• breaking The `codefresh` CLI now explicitly requires Node.js version 24.0.0 or higher. Running with older Node.js versions will result in an error and prevents the CLI from functioning.
  Fix: Upgrade your Node.js installation to version 24.0.0 or newer (e.g., using `nvm install 24 && nvm use 24`).
• breaking Multiple security vulnerabilities were addressed in recent releases, including fixes for supply chain issues and updated dependencies. Older versions may contain known security flaws.
  Fix: It is highly recommended to upgrade to the latest stable version of the `codefresh` CLI immediately to ensure security (`npm install -g codefresh@latest`).
• gotcha The `codefresh` package is a command-line interface tool, not a JavaScript library. It is not designed for direct programmatic import (`import {} from 'codefresh'`). Its functionality is exposed via shell commands.
  Fix: Interact with the CLI by executing `codefresh` commands as a child process from your JavaScript/TypeScript code (e.g., using Node.js `child_process` or a library like `execa`).
• gotcha Authentication with the Codefresh CLI relies on API keys. Storing API keys directly in source code or committing them to version control poses a significant security risk.
  Fix: Always use environment variables (e.g., `process.env.CODEFRESH_API_KEY`) or secure secret management systems to provide API keys to the CLI, especially in CI/CD environments.

Install

• npm install codefresh npm
• yarn add codefresh yarn
• pnpm add codefresh pnpm

Imports

• CLI Execution

  import { execa } from 'execa'; await execa('codefresh', ['version']);

  The `codefresh` package is primarily a command-line interface. For programmatic interaction in JavaScript/TypeScript, it's typically invoked as a child process using tools like `execa` or Node.js's built-in `child_process` module. Direct `import` or `require` of its internal modules is not officially supported or recommended for external use.
• Executable Path

  import { fileURLToPath } from 'url'; import { dirname, join } from 'path'; const __dirname = dirname(fileURLToPath(import.meta.url)); const cliPath = join(__dirname, 'node_modules', '.bin', 'codefresh');

  When installed globally (`npm install -g codefresh`), the `codefresh` executable is added to the system's PATH. When installed locally (e.g., as a development dependency), its executable is located in `node_modules/.bin/codefresh`.
• Library Import (Discouraged)
  wrong:

  import { getBuilds } from 'codefresh'; // This is not an exposed library API.

  correct:
  The `codefresh` package is not designed to be imported as a standard JavaScript/TypeScript library. Its functionality is exposed exclusively via the command-line interface, and attempts to import functions or objects directly will fail.

Quickstart

Demonstrates global installation of the Codefresh CLI, authentication using an API key from environment variables, and fetching the CLI version and configured contexts programmatically.

import { execa } from 'execa'; // npm install execa

async function setupAndUseCodefreshCLI() {
  console.log('--- Installing Codefresh CLI globally ---\n');
  try {
    await execa('npm', ['install', '-g', 'codefresh'], { stdio: 'inherit' });
    console.log('\nCodefresh CLI installed successfully.\n');
  } catch (error) {
    console.error('Failed to install Codefresh CLI:', error.message);
    return;
  }

  const apiKey = process.env.CODEFRESH_API_KEY ?? '';
  if (!apiKey) {
    console.error('CODEFRESH_API_KEY environment variable is not set. Please generate an API key from Codefresh account settings and set it.\n');
    return;
  }

  console.log('--- Authenticating with Codefresh CLI ---\n');
  try {
    await execa('codefresh', ['auth', 'create-context', '--api-key', apiKey], { stdio: 'inherit' });
    console.log('\nAuthentication successful. Context created.\n');
  } catch (error) {
    console.error('Authentication failed. Check your API key and network connection:', error.message);
    return;
  }

  console.log('--- Getting Codefresh CLI version ---\n');
  try {
    const { stdout } = await execa('codefresh', ['version']);
    console.log(`Codefresh CLI Version: ${stdout.trim()}\n`);
  } catch (error) {
    console.error('Failed to get CLI version:', error.message);
  }

  console.log('--- Listing Codefresh contexts (example) ---\n');
  try {
    const { stdout } = await execa('codefresh', ['get', 'contexts']);
    console.log('Codefresh Contexts:\n', stdout);
  } catch (error) {
    console.error('Failed to list contexts:', error.message);
  }
}

setupAndUseCodefreshCLI();