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

> Explore the comprehensive command-line interface options for typescript-go. Learn to use standard compilation, watch mode, and project references with this complete guide.

- Repository: [Microsoft/typescript-go](https://github.com/microsoft/typescript-go)
- Tags: api-reference
- Published: 2026-04-25

---

**The typescript-go CLI processes arguments through a declarative options system defined in [`internal/tsoptions/declscompiler.go`](https://github.com/microsoft/typescript-go/blob/main/internal/tsoptions/declscompiler.go) and parsed by [`internal/tsoptions/commandlineparser.go`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/cmd/tsgo/main.go), which extracts command-line arguments from `os.Args` and delegates to the execution engine.

```go
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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/tsconfig.json) or inline flags.

**Key options:**
- **`--project` (`-p`)**: Specifies the path to a [`tsconfig.json`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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:

```bash
tsgo --help

```

Display all available compiler flags:

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

```bash
tsgo file.ts

```

Compile a project using a specific configuration:

```bash
tsgo -p ./tsconfig.json

```

Start watch mode for incremental builds:

```bash
tsgo --watch -p .

```

Build a composite project with dependencies:

```bash
tsgo -b

```

Initialize a new project configuration:

```bash
tsgo --init

```

Type-check without emitting files, suppressing colorized output:

```bash
tsgo --noEmit --pretty false

```

Load arguments from a response file:

```bash
tsgo @args.txt

```

List files that would be compiled without building:

```bash
tsgo --listFilesOnly

```

## Summary

- **typescript-go** implements CLI parity with the official TypeScript compiler through a declarative options system in [`internal/tsoptions/declscompiler.go`](https://github.com/microsoft/typescript-go/blob/main/internal/tsoptions/declscompiler.go)
- The entry point at [`cmd/tsgo/main.go`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/internal/tsoptions/commandlineparser.go), supporting response files (`@file`) and type validation
- Help output in [`internal/execute/tsc/help.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/tsc/help.go) renders directly from option metadata, ensuring documentation accuracy
- Watch mode (`--watch`) utilizes [`internal/execute/watcher.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/watcher.go) for incremental rebuilds

## Frequently Asked Questions

### How does typescript-go handle response files?

The parser in [`internal/tsoptions/commandlineparser.go`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/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`](https://github.com/microsoft/typescript-go/blob/main/internal/tsoptions/commandlineoption.go), providing the single source of truth used by both the parser and help generator.