generated: '2026-08-06'
method: searched
source: https://refitter.github.io/articles/cli-tool.html
sources:
  - https://refitter.github.io/articles/cli-tool.html
  - https://raw.githubusercontent.com/christianhelle/refitter/main/docs/docfx_project/articles/cli-tool.md
  - https://raw.githubusercontent.com/christianhelle/refitter/main/docs/docfx_project/articles/docker.md
name: refitter
description: >-
  Refitter's first-party command line tool. Reads an OpenAPI 2.0 / 3.x
  specification from a file path or URL and generates C# Refit interfaces and
  contract types. Distributed as a .NET global tool (`Refitter` on NuGet) and as
  a container image (`christianhelle/refitter` on Docker Hub). The CLI, the
  MSBuild task and the source generator are all driven by the same `.refitter`
  settings file.
binary: refitter
system_requirements:
  runtime: .NET 8.0 or later
  bundled_runtimes: [net8.0, net9.0, net10.0]
install:
  - method: dotnet-tool
    command: dotnet tool install --global Refitter
    package: https://www.nuget.org/packages/Refitter
  - method: docker
    command: docker pull christianhelle/refitter
    image: https://hub.docker.com/r/christianhelle/refitter
    docs: https://refitter.github.io/articles/docker.html
usage: refitter [URL or input file] [OPTIONS]
arguments:
  - name: '[URL or input file]'
    description: URL or file path to the OpenAPI Specification file
options:
  general:
    - {flag: -h, alias: --help, description: Prints help information}
    - {flag: -v, alias: --version, description: Prints version information}
    - {flag: -s, alias: --settings-file, description: 'Path to .refitter settings file; specifying it ignores all other settings except --output'}
    - {flag: --no-banner, description: Don't show donation banner}
    - {flag: --simple-output, description: No color, formatting, emojis or banners — suitable for terminal or IDE output}
    - {flag: --no-logging, description: Don't log errors or collect telemetry}
  naming_and_output:
    - {flag: -n, alias: --namespace, default: GeneratedCode, description: Default namespace for generated types}
    - {flag: --contracts-namespace, description: Default namespace for generated contracts}
    - {flag: -o, alias: --output, default: Output.cs, description: Path to output file or folder}
    - {flag: --contracts-output, description: Output path for generated contracts (implies multiple files)}
    - {flag: --multiple-files, description: 'Generate RefitInterfaces.cs, DependencyInjection.cs and Contracts.cs instead of one file'}
    - {flag: --additional-namespace, description: Add an additional namespace to generated types (repeatable)}
    - {flag: --exclude-namespace, description: Exclude a namespace on generated types}
    - {flag: --no-auto-generated-header, description: Don't add the <auto-generated> header}
    - {flag: --internal, description: Set generated type accessibility to internal}
  interface_shape:
    - {flag: --interface-only, description: Don't generate contract types}
    - {flag: --contract-only, description: Don't generate clients}
    - {flag: --use-api-response, description: 'Return Task<IApiResponse<T>> instead of Task<T>'}
    - {flag: --use-observable-response, description: Return IObservable instead of Task}
    - {flag: --cancellation-tokens, description: Use cancellation tokens}
    - {flag: --disposable, description: Generate Refit clients that implement IDisposable}
    - {flag: --multiple-interfaces, description: 'Generate a Refit interface per endpoint — ByEndpoint or ByTag'}
    - {flag: --operation-name-template, description: "Generate operation names from a pattern using {operationName}"}
    - {flag: --operation-name-generator, default: Default, description: 'NSwag IOperationNameGenerator implementation (Default, MultipleClientsFromOperationId, MultipleClientsFromPathSegments, MultipleClientsFromFirstTagAndOperationId, MultipleClientsFromFirstTagAndOperationName, MultipleClientsFromFirstTagAndPathSegments, SingleClientFromOperationId, SingleClientFromPathSegments)'}
    - {flag: --immutable-records, description: Generate contracts as immutable records instead of classes}
  filtering:
    - {flag: --tag, description: Only include endpoints carrying this tag (repeatable, OR'ed)}
    - {flag: --match-path, description: Only include paths matching this regular expression (repeatable)}
    - {flag: --trim-unused-schema, description: Remove unreferenced component schemas}
    - {flag: --keep-schema, description: Force-keep schemas matching a regex; use with --trim-unused-schema (repeatable)}
    - {flag: --include-inheritance-hierarchy, description: Keep inherited/union types even when not directly used}
    - {flag: --no-deprecated-operations, description: Don't generate deprecated operations}
  headers_and_serialization:
    - {flag: --no-operation-headers, description: Don't generate operation headers}
    - {flag: --no-accept-headers, description: Don't add Accept headers}
    - {flag: --use-iso-date-format, description: Format date query string parameters as ISO 8601 (2023-06-15)}
    - {flag: --collection-format, default: Multi, description: 'Collection parameter format — Multi, Csv, Ssv, Tsv, Pipes'}
    - {flag: --use-polymorphic-serialization, description: Use System.Text.Json polymorphic serialization instead of NSwag JsonInheritanceConverter}
    - {flag: --no-inline-json-converters, description: Don't inline JsonConverter attributes for enum properties}
    - {flag: --integer-type, default: int, description: '.NET type for OpenAPI integer without a format (int, long)'}
    - {flag: --json-library-version, description: 'System.Text.Json version (default 8.0); 9.0+ enables JsonStringEnumMemberName'}
    - {flag: --optional-nullable-parameters, description: Generate nullable parameters as optional parameters}
    - {flag: --skip-default-additional-properties, description: Skip default additional properties}
  validation_and_security:
    - {flag: --skip-validation, description: Skip validation of the OpenAPI specification}
    - {flag: --allow-remote-refs, description: 'Resolve remote (http/https) $ref references inside the document. Disabled by default to prevent generation-time SSRF'}
  integrations:
    - {flag: --use-apizr, description: 'Generate for Apizr — IApizrRequestOptions parameter, Apizr cancellation tokens, method overloads (https://www.apizr.net)'}
    - {flag: --use-dynamic-querystring-parameters, description: Wrap multiple query parameters into a single complex parameter}
    - {flag: --custom-template-directory, description: Custom directory of NSwag fluid templates for code generation}
  telemetry_internal:
    - {flag: --telemetry-source, description: 'Reports the invocation source (e.g. msbuild); used internally by the MSBuild integration'}
    - {flag: --telemetry-file-count, description: Reports the number of settings files in the current workload}
    - {flag: --telemetry-runtime, description: Reports the bundled runtime selected for this invocation}
flows:
  - name: Generate a client from a local spec
    command: refitter ./openapi.json --namespace "Your.Namespace.GeneratedCode" --output ./GeneratedCode.cs
  - name: Generate a client straight from a remote spec URL
    command: refitter https://petstore3.swagger.io/api/v3/openapi.yaml
  - name: Generate from a checked-in settings file
    command: refitter ./openapi.json --settings-file ./openapi.refitter --output ./GeneratedCode.cs
  - name: One interface per tag, trimmed to what is used
    command: refitter ./openapi.json --multiple-interfaces ByTag --tag Pet --tag Store --trim-unused-schema
  - name: Run in a container
    command: docker run --rm -v ${PWD}:/data christianhelle/refitter /data/openapi.json
settings_file:
  name: .refitter
  format_docs: https://refitter.github.io/articles/refitter-file-format.html
  json_schema: json-schema/refitter-refitter-file-schema.json
  note: >-
    The same .refitter settings file drives the CLI, the MSBuild task and the
    source generator. New CLI arguments are required by the project's own
    contribution rules to be documented in README.md and in the .refitter file
    format docs.
telemetry:
  collected: true
  scope: anonymous usage telemetry and error reports
  opt_out: --no-logging
x-evidence:
  fetched: '2026-08-06'
  probes:
    - url: https://refitter.github.io/articles/cli-tool.html
      status: 200
    - url: https://raw.githubusercontent.com/christianhelle/refitter/main/docs/docfx_project/articles/cli-tool.md
      status: 200