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,
  id: cliFlag,
  description: () => <>Description shown in docs.</>,
  ssrName: null, // or 'myFlag' if used in SSR APIs
  docLink: 'https://www.remotion.dev/docs/options/my-flag',
  type: false as boolean, // TypeScript type witness; defaults are resolved in getValue
  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: <value> as T determines the option's value type. Use boolean, string | null, number | null, etc.

The id must be unique and contain only lowercase letters, digits, and hyphens. It determines the /docs/options/<id> page and the <Options id="..." /> value. It usually matches cliFlag, but shared flags can have distinct option IDs.

Set docLink to https://www.remotion.dev/docs/options/<id>.

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.

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 id value

CLI help metadata: Add the flag to each supported command's option list in packages/cli/src/print-help.ts, packages/lambda/src/cli/help.ts, or packages/cloudrun/src/cli/help.ts. The generated option page uses the help entries' optionIds to list supported commands; ensure shared flags resolve to the correct option ID.

API pages: Document each public parameter under its own heading so the generated page can link to it.

packages/docs/docs/config.mdx:

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

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

Generated option reference: Generate packages/docs/docs/options/<id>.mdx and the options index using the commands below. Edit the option definition and API/config docs rather than the generated MDX. Option pages are added to the sidebar automatically.

7. Build and verify

# From the repository root
bun run build
cd packages/docs
bun run generate-option-docs
bun run render-cards
bun run check-option-docs

Verify /docs/options/<id> includes the description, supported commands, and relevant API/configuration links. Commit the generated page and index, the article catalog (packages/docs/src/data/articles.ts), and the new social preview card.

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