CLI Plugins

Add custom commands to the orgp CLI using the CreateCommand factory.

Adding a CLI Command

import { CreateCommand } from "org-press";

export const myCommand = CreateCommand("mycommand", {
  description: "Do something useful",
  args: {
    output: {
      flag: "-o, --output <dir>",
      description: "Output directory",
    },
    verbose: {
      flag: "-v, --verbose",
      description: "Verbose output",
    },
  },
  execute: async (args, ctx) => {
    console.log("Running mycommand");
    console.log("Output:", args.output);
    console.log("Verbose:", args.verbose);
    return 0; // exit code
  },
});

CreateCommand API

CreateCommand(name: string, options: CommandOptions): OrgPressPlugin

interface CommandOptions {
  /** Description shown in --help */
  description: string;

  /** Command arguments/flags */
  args?: Record<string, ArgDefinition>;

  /** Command implementation */
  execute: (args: ParsedArgs, ctx: CommandContext) => Promise<number>;
}

interface ArgDefinition {
  /** Flag format: "-s, --long <value>" or "-f, --flag" for boolean */
  flag: string;

  /** Description for --help */
  description: string;

  /** Default value */
  default?: unknown;

  /** Short alias (auto-extracted from flag if present) */
  alias?: string;
}

interface CommandContext {
  /** Resolved org-press config */
  config: OrgPressConfig;

  /** All loaded plugins */
  plugins: OrgPressPlugin[];

  /** Working directory */
  cwd: string;
}

Built-in CLI Commands

These commands are included with org-press:

Example: Custom Test Runner

import { CreateCommand } from "org-press";

export const testCommand = CreateCommand("test", {
  description: "Run tests in :use test blocks",
  args: {
    watch: {
      flag: "-w, --watch",
      description: "Watch mode",
    },
    coverage: {
      flag: "--coverage",
      description: "Collect coverage",
    },
    filter: {
      flag: "-f, --filter <pattern>",
      description: "Filter tests by name",
    },
  },
  execute: async (args, ctx) => {
    const { watch, coverage, filter } = args;

    // Find all test blocks in the project
    // Run vitest with options
    console.log("Running tests...");

    if (watch) {
      console.log("Watch mode enabled");
    }

    return 0;
  },
});

Registering Commands

Commands are registered like any other plugin:

// .org-press/config.ts
import { defineConfig } from "org-press";
import { myCommand } from "./plugins/my-command";

export default defineConfig({
  plugins: [myCommand],
});

Then use it: