Add a new CLI option

How to convert a hardcoded CLI flag into a proper AnyRemotionOption, or add a brand new one.

1. Create the option definition

Create packages/renderer/src/options/<name>.tsx:

import type {AnyRemotionOption} from './option';

let myValue = false; // module-level default state

const cliFlag = 'my-flag' as const;

export const myFlagOption = {
  name: 'Human-readable Name',
  cliFlag,
  description: () => <>Description shown in docs.</>,
  ssrName: null, // or 'myFlag' if used in SSR APIs
  docLink: 'https://www.remotion.dev/docs/config#setmyflagenabled',
  type: false as boolean, // default value, also sets the TypeScript type
  getValue: ({commandLine}) => {
    if (commandLine[cliFlag] !== undefined) {
      return {value: commandLine[cliFlag] as boolean, source: 'cli'};
    }
    return {value: myValue, source: 'config'};
  },
  setConfig(value) {
    myValue = value;
  },
} satisfies AnyRemotionOption<boolean>;

The type in AnyRemotionOption<T> and type: <default> as T determines the option's value type. Use boolean, string | null, number | null, etc.

For negating flags (like --disable-ask-ai → askAIEnabled = false), handle the inversion in getValue.

2. Register in options index

packages/renderer/src/options/index.tsx:

• Add the import (keep alphabetical within the import block)
• Add the option to the allOptions object

This makes it available as BrowserSafeApis.options.myFlagOption throughout the codebase.

3. Update CLI parsed flags

packages/cli/src/parsed-cli.ts:

• For boolean flags, add BrowserSafeApis.options.myFlagOption.cliFlag to the BooleanFlags array
• For non-boolean flags, no entry needed here (minimist handles them as strings/numbers automatically)

packages/cli/src/parse-command-line.ts:

• Add to the destructured BrowserSafeApis.options
• In the CommandLineOptions type, add: [myFlagOption.cliFlag]: TypeOfOption<typeof myFlagOption>;

4. Use the option where needed

Instead of reading parsedCli['my-flag'] directly, resolve via:

const myFlag = myFlagOption.getValue({commandLine: parsedCli}).value;

For Studio options, this is typically in packages/cli/src/studio.ts. For render options, in the relevant render command file.

If the option is consumed by Studio, read ../studio-config-option-lifecycle/SKILL.md completely before wiring it. Classify the option as startup-fixed or reloadable across all Studio consumers; mixed behavior is not allowed. If any consumer requires startup-fixed behavior, pass the startup snapshot to every consumer. Add lifecycle tests that prove the classification.

5. Add to Config

packages/cli/src/config/index.ts:

• Add to the destructured BrowserSafeApis.options
• Add the setter signature to the FlatConfig type (either in the RemotionConfigObject global interface or the FlatConfig intersection)
• Add the implementation to the Config object: setMyFlagEnabled: myFlagOption.setConfig

6. Update docs — IMPORTANT, do not skip this step

This step is mandatory. Every new option must have its docs updated to use <Options id="..." /> so the description is pulled from the option definition automatically (single source of truth). If converting an existing hardcoded flag, replace any hand-written description with the <Options> component.

CLI command pages (check all that apply — cli/render.mdx, lambda/cli/render.mdx, cloudrun/cli/render.mdx, cli/benchmark.mdx):

• Add or update the ### \--my-flag`` section
• Use <Options id="my-flag" /> as the description body (no import needed — it's globally available)
• The id must match the option's cliFlag / id value

packages/docs/docs/config.mdx:

• Add or update the ## \setMyFlagEnabled()`` section with:
  • <Options id="my-flag" /> for the description
  • A twoslash config example
  • A note that the CLI flag takes precedence

Follow the pattern of nearby entries (e.g., setAskAIEnabled, setEnableCrossSiteIsolation).

7. Build and verify

cd packages/renderer && bun run make
cd packages/cli && bun run make

Reference files

• Option type definition: packages/renderer/src/options/option.ts
• Good example to copy: packages/renderer/src/options/ask-ai.tsx (boolean, studio-only)
• Options index: packages/renderer/src/options/index.tsx
• CLI flag registration: packages/cli/src/parsed-cli.ts
• CLI type definitions: packages/cli/src/parse-command-line.ts
• Config registration: packages/cli/src/config/index.ts