Add Cli Option
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.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Add Cli Option when an AI agent needs a reusable SKILL.md workflow for this job: 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.
When not to use it
Skip Add Cli Option when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/add-cli-option # Save SKILL.md to ~/.claude/skills/add-cli-option/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/add-cli-option/SKILL.md. For a shared project, commit the folder at .claude/skills/add-cli-option/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Add Cli Option skill for this task: Use Add Cli Option when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 70/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# 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`
Intended uses
- Use Add Cli Option when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.