Reference CLI

All CLI flags can also be set in the config file. CLI flags override config file options.

Flag Patterns

CLI flag mapping rules:

• --foo sets foo: true
• --no-foo sets foo: false
• --foo.bar sets foo: { bar: true }
• --format esm --format cjs sets format: ['esm', 'cjs']

CLI flags support both camelCase and kebab-case. For example, --outDir and --out-dir are equivalent.

Basic Commands

Build

Configuration

--config, -c <filename>

Specify custom config file:

--no-config

Disable config file loading:

--config-loader <loader>

Choose config loader (auto, native, unrun):

--tsconfig <file>

Specify TypeScript config file:

Entry Points

[...files]

Specify entry files as arguments:

Output Options

--format <format>

Output format (esm, cjs, iife, umd):

--out-dir, -d <dir>

Output directory:

--dts

Generate TypeScript declarations:

--clean

Clean output directory before build:

Build Options

--target <target>

JavaScript target version:

--platform <platform>

Target platform (node, browser, neutral):

--minify

Enable minification:

--sourcemap

Generate source maps:

--treeshake

Enable/disable tree shaking:

Dependencies

--deps.never-bundle <module>

Mark module as external (not bundled):

--deps.skip-node-modules-bundle

Skip resolving and bundling all node_modules:

--shims

Add ESM/CJS compatibility shims:

Development

--watch, -w [path]

Enable watch mode:

--ignore-watch <path>

Ignore paths in watch mode:

--on-success <command>

Run command after successful build:

Environment Variables

--env.* <value>

Set compile-time environment variables:

Access as import.meta.env.* or process.env.*.

--env-file <file>

Load environment variables from file:

--env-prefix <prefix>

Filter environment variables by prefix (default: TSDOWN_):

Assets

--copy <dir>

Copy directory to output:

Executable

--exe

[experimental] Bundle as a standalone executable using Node.js Single Executable Applications (opens in a new tab). Requires Node.js >= 25.5.0, not supported in Bun or Deno. Cross-platform builds supported via @tsdown/exe.

When enabled:

• Default format changes to cjs (unless Node.js >= 25.7.0)
• Declaration file generation (dts) is disabled by default
• Code splitting is disabled
• Only single entry points are supported

See Executable for advanced configuration and cross-platform builds.

Package Management

--exports

Generate the exports field in package.json:

--publint

Enable package validation:

--attw

Enable “Are the types wrong” validation:

--unused

Check for unused dependencies:

Logging

--log-level <level>

Set logging verbosity (silent, error, warn, info):

--report / --no-report

Enable/disable build report:

--debug [feat]

Show debug logs:

Integration

--from-vite [vitest]

Extend Vite or Vitest config:

Workspace / Monorepo

--workspace, -W [dir]

Enable workspace mode for building multiple packages:

--filter, -F <pattern>

Filter configs by name or working directory. Supports regex:

--unbundle

Enable unbundle (bundleless) mode:

--root <dir>

Specify the root directory of input files (similar to TypeScript’s rootDir). Controls the output directory structure by determining how entry file paths map to output paths. Defaults to the common base directory of all entry files.

--fail-on-warn

Fail on warnings (enabled by default):

Common Usage Patterns

Basic Build

Library (ESM + CJS + Types)

Production Build

Development (Watch)

Browser Bundle (IIFE)

Node.js CLI Tool

Standalone Executable

Monorepo Package

With Environment Variables

Copy Assets

Tips

1. Use config file for complex setups
2. CLI flags override config file options
3. Chain multiple formats for multi-target builds
4. Use --clean to avoid stale files
5. Enable --dts for TypeScript libraries
6. Use --watch during development
7. Add --on-success for post-build tasks
8. Use --exports to auto-generate package.json fields

Related Documentation

• Config File - Configuration file options
• Entry - Entry point configuration
• Output Format - Format options
• Watch Mode - Watch mode details