Command-Line Interface Options for typescript-go: Complete Reference and Usage Guide

The typescript-go CLI processes arguments through a declarative options system defined in internal/tsoptions/declscompiler.go and parsed by internal/tsoptions/commandlineparser.go, supporting standard compilation, watch mode, and project references with full parity to the official TypeScript compiler.

The typescript-go project is Microsoft's native Go implementation of the TypeScript compiler (tsc). Its command-line interface replicates the official TypeScript compiler behavior through a single source of truth for option definitions that ensures parsing, validation, and documentation remain synchronized. This guide examines the CLI architecture, option parsing pipeline, and practical usage patterns derived directly from the source code.

CLI Architecture and Entry Points

Program execution begins in cmd/tsgo/main.go, which extracts command-line arguments from os.Args and delegates to the execution engine.

result := execute.CommandLine(newSystem(), args, nil)

The newSystem() abstraction supplies OS-level services including filesystem access, stdout handling, and terminal width detection. The CommandLine function in internal/execute/tsc.go serves as the high-level dispatcher, examining the first argument to determine the execution mode. If it detects -b or --build, it forwards to tscBuildCompilation; otherwise, it proceeds to tscCompilation for standard compilation.

How Options Are Defined and Parsed

The typescript-go CLI uses a declarative options database that eliminates drift between parsing logic and help documentation.

The Options Schema

All CLI flags are defined by the CommandLineOption struct in internal/tsoptions/commandlineoption.go. Each declaration specifies:

• Name and ShortName (e.g., --watch, -w)
• Kind (string, boolean, list, enum)
• Category for help grouping
• Description using localized diagnostic messages
• DefaultValueDescription for help output

The master slice OptionsDeclarations in internal/tsoptions/declscompiler.go aggregates these definitions, built from commonOptionsWithBuild (shared with build mode) and optionsForCompiler (compilation-specific flags). This list is indexed into CommandLineCompilerOptionsMap for fast lookups during parsing.

Argument Parsing Pipeline

The parseCommandLineWorker function in internal/tsoptions/commandlineparser.go transforms raw arguments into a ParsedCommandLine structure. The parser handles:

• Response files: @file.txt syntax expands additional arguments from disk
• Boolean shortcuts: Flags like --strict toggle true without explicit values
• Value validation: Enum membership and numeric ranges are verified via validateJsonOptionValue
• Ordered maps: Results populate parser.options maintaining declaration order

Compilation Modes and Key Flags

The CLI supports three primary execution modes, each utilizing the same underlying options model.

Standard Compilation

The default mode compiles TypeScript files or projects using configuration from tsconfig.json or inline flags.

Key options:

• --project (-p): Specifies the path to a tsconfig.json file
• --target: Sets the ECMAScript target (e.g., es2022)
• --module: Determines the module system (e.g., esnext, commonjs)
• --outDir: Redirects emitted JavaScript to a specific directory
• --noEmit: Performs type-checking without writing output files
• --strict: Enables all strict type-checking options

Build Mode

The -b or --build flag activates tscBuildCompilation for composite projects. This mode orchestrates builds across referenced projects declared in tsconfig.json references arrays, respecting dependency order and incremental compilation boundaries.

Watch Mode

Specifying --watch (-w) creates a Watcher instance via internal/execute/watcher.go. The watcher monitors source files for changes and triggers incremental recompilation automatically, reusing the parsed options from the initial invocation.

Help System and Option Discovery

When --help is detected, the CLI renders documentation using the same metadata structures that drive the parser, ensuring accuracy.

Help Generation Functions

Located in internal/execute/tsc/help.go:

• printEasyHelp: Renders the simplified view showing only ShowInSimplifiedHelpView options
• printAllHelp: Displays the complete sorted list from OptionsDeclarations

The generateSectionOptionsOutput function groups options by their Category field (e.g., Command line options, Modules, Emit), while generateOptionOutput formats individual entries with descriptions, possible values from getValueCandidate, and default values, respecting terminal width constraints.

Usage Examples

Display concise help:

tsgo --help

Display all available compiler flags:

tsgo --help --all

Practical Usage Examples

The following commands demonstrate common typescript-go workflows. Replace tsgo with your compiled binary path.

Compile a single file with default options:

tsgo file.ts

Compile a project using a specific configuration:

tsgo -p ./tsconfig.json

Start watch mode for incremental builds:

tsgo --watch -p .

Build a composite project with dependencies:

tsgo -b

Initialize a new project configuration:

tsgo --init

Type-check without emitting files, suppressing colorized output:

tsgo --noEmit --pretty false

Load arguments from a response file:

tsgo @args.txt

List files that would be compiled without building:

tsgo --listFilesOnly

Summary

• typescript-go implements CLI parity with the official TypeScript compiler through a declarative options system in internal/tsoptions/declscompiler.go
• The entry point at cmd/tsgo/main.go delegates to execute.CommandLine, which dispatches to either standard compilation or build mode based on the -b flag
• All options are defined once in OptionsDeclarations and parsed by internal/tsoptions/commandlineparser.go, supporting response files (@file) and type validation
• Help output in internal/execute/tsc/help.go renders directly from option metadata, ensuring documentation accuracy
• Watch mode (--watch) utilizes internal/execute/watcher.go for incremental rebuilds

Frequently Asked Questions

How does typescript-go handle response files?

The parser in internal/tsoptions/commandlineparser.go detects arguments prefixed with @ and expands them using parseResponseFile. This allows users to store lengthy command-line configurations in text files and reference them via tsgo @args.txt, with the expanded arguments inserted directly into the parsing queue.

What is the difference between --help and --help --all?

The --help flag triggers printEasyHelp, which filters the OptionsDeclarations slice to show only entries where ShowInSimplifiedHelpView is true. Appending --all invokes printAllHelp, rendering the complete set of compiler options sorted by category. Both methods use the same formatting pipeline in internal/execute/tsc/help.go.

How does the build mode (-b) differ from standard compilation?

Standard compilation (tscCompilation) processes individual files or a single project configuration. Build mode (tscBuildCompilation) specifically handles composite projects with references in tsconfig.json, building dependencies in topological order and utilizing incremental build information. Build-specific options are shared through commonOptionsWithBuild in the options declarations.

Where are CLI option definitions sourced from in the codebase?

Option definitions reside in internal/tsoptions/declscompiler.go as a master slice named OptionsDeclarations, constructed from commonOptionsWithBuild and optionsForCompiler. Each entry conforms to the CommandLineOption struct defined in internal/tsoptions/commandlineoption.go, providing the single source of truth used by both the parser and help generator.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}