Skip to content

Conversation

@haydenbleasel
Copy link

@haydenbleasel haydenbleasel commented Jan 8, 2026

Summary

Implements support for passing arbitrary CLI flags through to procedures without explicitly defining each one in the schema. This resolves #161.

Key changes:

  • Added allowUnknownOptions?: boolean to TrpcCliMeta interface
  • Added hasAdditionalProperties?: boolean to ParsedProcedure interface
  • Modified schema parsing to track additionalProperties instead of rejecting them
  • Configured Commander.js to allow unknown options when the feature is enabled
  • Added parseUnknownOptions() helper to parse and merge unknown CLI options into procedure input
  • Maintained backward compatibility: schemas with additionalProperties still fall back to JSON input mode unless allowUnknownOptions is explicitly enabled

Usage

const router = t.router({
  forward: t.procedure
    .meta({ allowUnknownOptions: true })
    .input(z.object({ known: z.string().optional() }).passthrough())
    .query(({ input }) => {
      // input contains both known and unknown options
      console.log(input)
    }),
})
mycli forward --known value --unknown-flag foo --another-flag bar
# input: { known: "value", unknownFlag: "foo", anotherFlag: "bar" }

Features

  • Kebab-to-camelCase conversion: --my-option becomes myOption
  • Boolean flags: --flag sets flag: true
  • Negated flags: --no-flag sets flag: false
  • Equals syntax: --key=value works as expected
  • Type coercion: Numeric strings become numbers, "true"/"false" become booleans

Requirements

Both conditions must be met for passthrough to work:

  1. Procedure meta must have allowUnknownOptions: true
  2. Input schema must allow additional properties (e.g. .passthrough() or z.record())

Use Case

This is particularly useful for building CLI wrappers around other tools (like the Ultracite/Biome example mentioned in the issue) where you want to forward flags without manually enumerating every possible option.

Test plan

  • Added tests for allowUnknownOptions with passthrough schema
  • Added tests for allowUnknownOptions with record schema
  • Added tests verifying backward compatibility (schemas with additionalProperties but without allowUnknownOptions fall back to JSON input)
  • Added tests verifying that allowUnknownOptions alone (without schema support) doesn't enable passthrough
  • All existing tests pass

Documentation

  • Added "Passthrough/Unknown Options" section to README
  • Updated "Advanced Meta Configuration" to mention allowUnknownOptions
  • Added feature to "Features and Limitations" list

Closes #161

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature Request: Support for passthrough/arbitrary CLI flags

1 participant