can1357/oh-my-pi · error · Error

unknown flag: ${arg} (see --help)

Error message

unknown flag: ${arg} (see --help)

What it means

parseArgs has a fixed set of recognized flags; the default branch throws for anything unrecognized, appending '(see --help)' to point at the documentation. This is the standard argparse-style fail-fast for mistyped or unsupported flags.

Source

Thrown at packages/metaharness/src/runner.ts:362

				const eq2 = spec.indexOf("=");
				if (eq2 === -1) {
					const hostVal = process.env[spec];
					if (hostVal !== undefined) cfg.env[spec] = hostVal;
				} else {
					cfg.env[spec.slice(0, eq2)] = spec.slice(eq2 + 1);
				}
				break;
			}
			case "--environment": {
				const v = take(arg);
				if (v !== "docker" && v !== "apple-container") {
					throw new Error("--environment must be docker|apple-container");
				}
				cfg.envType = v;
				break;
			}
			default:
				throw new Error(`unknown flag: ${arg} (see --help)`);
		}
	}
	if (cfg.models.length === 0) cfg.models = ["anthropic/claude-sonnet-4-6"];
	if (cfg.envType === "apple-container") {
		if (cfg.hostNetwork) throw new Error("--host-network is docker-only (compose overlay)");
		// host.docker.internal doesn't exist on vmnet; containers reach the host at the bridge address.
		if (cfg.gatewayUrl === DOCKER_GATEWAY_URL) cfg.gatewayUrl = VMNET_GATEWAY_URL;
	}
	return cfg;
}

// ─────────────────────────────────────────────────────────────────── resume

/** manager.json launch record written by RunStore.registerLaunch. */
interface ManagerRecord {
	benchmark?: string;
	dataset?: string;
	config?: LaunchRequest;

View on GitHub (pinned to 9690622007)

Solutions

1. Run the runner with --help to list valid flags.
2. Fix the typo / use the full flag name — no shorthand forms exist.
3. Check the version you are running matches the docs (`runner --version`); flags may have been renamed.
4. Quote or guard interpolated variables in scripts so they don't expand into stray tokens: "${FLAG:-}".

Example fix

// before
runner --env docker
// after
runner --environment docker

const KNOWN_FLAGS = new Set(["--agent","--install","--binary","--no-build","--environment","--host-network","--version","--resume","--jobs-dir","--help"]);
const unknown = argv.filter(a => a.startsWith("--") && !KNOWN_FLAGS.has(a));
if (unknown.length) throw new Error(`unknown flags before invoking runner: ${unknown.join(",")}`);

function isKnownFlag(a: string): boolean {
  return a.startsWith("--") ? KNOWN_FLAGS.has(a) : true;
}

try {
  await runHarness(args);
} catch (e) {
  if (e instanceof Error && e.message.startsWith("unknown flag:")) {
    console.error(e.message + " — run the runner with --help for the valid flag list.");
  } else throw e;
}

When it happens

Trigger: Typos like `--jobname` instead of the real flag, `--env` as a shorthand that does not exist, passing a positional-looking stray token starting with '-', or using a flag from a different tool/version.

Common situations: Copying flags from an older/newer version of the runner; muscle-memory shorthand flags; pasting commands from blog posts about other harnesses; a shell variable expanding to an empty string leaving a dangling '-' prefix.

Related errors

• unknown file type: {value}
• invalid size: {value}
• 2
• invalid --block-size argument '{0}'
• invalid --time-style argument {} Possible values are: - [p

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/79df2c8f7e0d8c97. Report an issue: GitHub.