---
name: remotion-dev-add-cli-option
description: "Add a new Remotion CLI or config option by creating an AnyRemotionOption, registering CLI parsing, wiring config setters, and updating documentation. Use when adding or converting command-line flags or Remotion options."
license: "NOASSERTION"
metadata:
  decimalai-skill-id: "0c1b394c-46bf-4c84-ab4d-2d4342a8c815"
  decimalai-version-id: "d3f1d719-bc73-4903-9f22-b172f44fa664"
  decimalai-version: "3"
  decimalai-body-sha256: "c9b84096439ccb8043debe7b52ee56c73e11eb4245400d84135075d09d658ed1"
  decimalai-name: "remotion-dev/add-cli-option"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "coding"
  decimalai-source: "https://app.decimal.ai/s/remotion-dev-add-cli-option@3/SKILL.md"
---
# 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`:

```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:

```ts
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`](../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

```sh
# 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`