Add flag to CLI to specify config file

[jamescmartinez]

Closes #284

Implements a git options style config flag:

openworkflow worker start --config src/openworkflow.config.ts

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds support for specifying an explicit OpenWorkflow config file path via a new --config <path> CLI option, updating both CLI behavior and documentation to support configs stored outside the current working directory.

Changes:

• Added loadConfigFromPath() and refactored config importing to reuse a shared importer.
• Wired --config through CLI commands (init, doctor, worker start, dashboard) and ensured init can create configs in subdirectories.
• Updated docs to mention overriding the config path with --config.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/docs/docs/configuration.mdx	Documents using --config to point to a config file outside CWD.
packages/docs/docs/cli.mdx	Notes that CLI config path can be overridden with --config.
packages/cli/config.ts	Adds explicit-path config loading and consolidates import logic.
packages/cli/config.test.ts	Adds tests for explicit-path loading and “no fallback” behavior.
packages/cli/commands.ts	Threads optional config through command handlers and uses explicit-path loading.
packages/cli/cli.ts	Adds --config option to relevant subcommands.

Comments suppressed due to low confidence (3)

packages/cli/commands.ts:215

• When a user passes an explicit --config path and it doesn’t exist, loadConfigFromPath() returns an empty config and doctor() throws the generic "No config file found" message with an "init" suggestion. This is misleading for the explicit-path case (it’s a path error, not discovery). Consider detecting the missing explicit path and throwing a more specific CLIError (e.g., "Config file not found at ") without suggesting init, or add a throwIfMissing/required mode for loadConfigFromPath and use it here.

  const { config, configFile } = await loadConfigWithEnv(configPath);
  if (!configFile) {
    throw new CLIError(
      "No config file found.",
      "Run `npx @openworkflow/cli init` to create a config file.",
    );

packages/cli/commands.ts:276

• If --config is provided but the file doesn’t exist, loadConfigFromPath() yields an empty config and this path falls into the generic "No config file found" error. For worker start, that message/hint is confusing because the user did provide a path. Recommend treating a missing explicit path as a distinct error (include the resolved path) rather than the discovery/"run init" guidance.

  const { config, configFile } = await loadConfigWithEnv(configPath);
  if (!configFile) {
    throw new CLIError(
      "No config file found.",
      "Run `npx @openworkflow/cli init` to create a config file.",
    );

packages/cli/commands.ts:354

• Same as other commands: if a user passes --config and that file is missing, this will throw "No config file found" with guidance to run init, which doesn’t help diagnose a bad path. Consider producing a path-specific error when configPath is set but not found (ideally including the resolved absolute path).

  const { configFile } = await loadConfigWithEnv(configPath);
  if (!configFile) {
    throw new CLIError(
      "No config file found.",
      "Run `npx @openworkflow/cli init` to create a config file before starting the dashboard.",
    );

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Issue #284’s example usage shows openworkflow --config <path> worker start (a global option before the subcommand), but this implementation only defines --config on individual subcommands. As written, openworkflow --config … worker start will be rejected as an unknown option by Commander. Either add --config as a global option on the root program and plumb it through, or update the issue/CLI docs/PR scope to reflect that only openworkflow worker start --config … is supported.

[jamescmartinez]

already noted in the PR description