---
url: /reference/cli.md
---
# Command Line Interface

All CLI flags can also be set in the configuration file, which improves reusability and maintainability for complex projects. Conversely, any option can be overridden by CLI flags, even if not explicitly listed on this page. For more details, see the [Config File](../options/config-file.md) documentation.

## CLI Flag Patterns

The mapping between CLI flags and configuration options follows these 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. Nested keys follow the same rule, so `--deps.never-bundle` and `--deps.neverBundle` are equivalent as well.

Options whose keys are defined by you — `--env.*`, `--define.*`, `--alias.*`, `--entry.*` and `--loader.*` — are the exception: their keys are used exactly as written.

This flexible pattern allows you to easily control and override configuration options directly from the command line.

## `[...files]`

Specify entry files as command arguments. This is equivalent to setting the `entry` option in the configuration file. For example:

```bash
tsdown src/index.ts src/util.ts
```

This will bundle `src/index.ts` and `src/util.ts` as separate entry points. See the [Entry](../options/entry.md) documentation for more details.

## `-c, --config <filename>`

Specify a custom configuration file. Use this option to define the path to the configuration file you want to use.

See also [Config File](../options/config-file.md).

## `--config-loader <loader>`

Specifies which config loader to use: `auto` (default), `native`, `tsx`, or `unrun`.

See also [Config File](../options/config-file.md).

## `--no-config`

Disable loading a configuration file. This is useful if you want to rely solely on command-line options or default settings.

See also [Disabling the Config File](../options/config-file.md#disable-config-file).

## `--tsconfig <tsconfig>`

Specify the path or filename of your `tsconfig` file. `tsdown` will search upwards from the current directory to find the specified file. By default, it uses `tsconfig.json`.

```bash
tsdown --tsconfig tsconfig.build.json
```

## `-f, --format <format>`

Define the bundle format. Supported formats include:

* `esm` (ECMAScript Modules)
* `cjs` (CommonJS)
* `iife` (Immediately Invoked Function Expression)
* `umd` (Universal Module Definition)

See also [Output Format](../options/output-format.md).

## `--clean`

Clean the output directory before building. This removes all files in the output directory to ensure a fresh build. Enabled by default; use `--no-clean` to disable.

See also [Cleaning](../options/cleaning.md).

## `--deps.never-bundle <module>`

Mark a module as external. This prevents the specified module from being included in the bundle.

See also [Dependencies](../options/dependencies.md).

## `--external <module>` {#external}

::: warning Deprecated
Use `--deps.never-bundle` instead.
:::

Alias for `--deps.never-bundle`.

## `--minify`

Enable minification of the output bundle to reduce file size. Minification removes unnecessary characters and optimizes the code for production.

See also [Minification](../options/minification.md).

## `--target <target>`

Specify the JavaScript target version for the bundle. Examples include:

* `es2015`
* `esnext`
* `chrome100`
* `node18`

You can also disable all syntax transformations by using `--no-target` or by setting the target to `false` in your configuration file.

See also [Target](../options/target.md).

## `-l, --log-level <level>`

Set the log level to control the verbosity of logs during the build process. Available levels: `info`, `warn`, `error`, `silent`.

See also [Log Level](../options/log-level.md).

## `-d, --out-dir <dir>`

Specify the output directory for the bundled files. Use this option to customize where the output files are written.

See also [Output Directory](../options/output-directory.md).

## `--root <dir>`

Specify the root directory of input files.

See also [Root Directory](../options/root.md).

## `--treeshake`, `--no-treeshake`

Enable or disable tree shaking. Tree shaking removes unused code from the final bundle, reducing its size and improving performance.

See also [Tree Shaking](../options/tree-shaking.md).

## `--sourcemap`

Generate source maps for the bundled files. Source maps help with debugging by mapping the output code back to the original source files.

See also [Source Maps](../options/sourcemap.md).

## `--shims`

Enable CommonJS (CJS) and ECMAScript Module (ESM) shims. This ensures compatibility between different module systems.

See also [Shims](../options/shims.md).

## `--platform <platform>`

Specify the target platform for the bundle. Supported platforms include:

* `node` (Node.js)
* `browser` (Web browsers)
* `neutral` (Platform-agnostic)

See also [Platform](../options/platform.md).

## `--dts`

Generate TypeScript declaration (`.d.ts`) files for the bundled code. This is useful for libraries that need to provide type definitions.

See also [Declaration Files](../options/dts.md).

## `--publint`

Enable `publint` to validate your package for publishing. This checks for common issues in your package configuration, ensuring it meets best practices.

See also [Package Validation](../options/lint.md).

## `--attw`

Enable [Are the types wrong?](https://github.com/arethetypeswrong/arethetypeswrong.github.io) integration to check your package's TypeScript types for compatibility issues.

See also [Package Validation](../options/lint.md).

## `--unused`

Enable unused dependencies checking. This helps identify dependencies in your project that are not being used, allowing you to clean up your `package.json`.

## `-w, --watch [path]`

Enable watch mode to automatically rebuild your project when files change. Optionally, specify a path to watch for changes.

See also [Watch Mode](../options/watch-mode.md).

## `--ignore-watch <path>`

Ignore custom paths in watch mode.

## `--from-vite [vitest]`

Reuse configuration from Vite or Vitest. This allows you to extend or integrate with existing Vite or Vitest configurations seamlessly.

See also [Extending Vite or Vitest Config](../options/config-file.md#extending-vite-or-vitest-config-experimental).

## `--report`, `--no-report`

Enable or disable the generation of a build report. By default, the report is enabled and outputs the list of build artifacts along with their sizes to the console. This provides a quick overview of the build results, helping you analyze the output and identify potential optimizations. Disabling the report can be useful in scenarios where minimal console output is desired.

## `--devtools`

Enable Vite DevTools integration for bundle analysis.

## `--env.* <value>`

Define compile-time environment variables, for example:

```bash
tsdown --env.NODE_ENV=production
```

Note that environment variables defined with `--env.VAR_NAME` can only be accessed as `import.meta.env.VAR_NAME` or `process.env.VAR_NAME`.

## `--env-file <file>`

Load environment variables from a file. When used together with `--env`, variables in `--env` take precedence.

:::tip
To prevent accidental exposure of sensitive information, only environment variables prefixed with `TSDOWN_` are injected by default. You can customize this behavior using the [`--env-prefix`](#env-prefix) flag.
:::

```bash
tsdown --env-file .env.production
```

## `--env-prefix <prefix>` {#env-prefix}

When loading environment variables from a file via `--env-file`, only include variables that start with these prefixes.

* **Default:** `TSDOWN_`

```bash
tsdown --env-file .env --env-prefix APP_ --env-prefix TSDOWN_
```

## `--debug [feat]`

Show debug logs.

## `--on-success <command>`

Specify a command to run after a successful build. This is especially useful in watch mode to trigger additional scripts or actions automatically after each build completes.

```bash
tsdown --on-success "echo Build finished!"
```

## `--copy <dir>`

Copies all files from the specified directory to the output directory. This is useful for including static assets such as images, stylesheets, or other resources in your build output.

```bash
tsdown --copy public
```

All contents of the `public` directory will be copied to your output directory (e.g., `dist`).

## `--exe`

**\[experimental]** Bundle as a standalone executable using [Node.js Single Executable Applications](https://nodejs.org/api/single-executable-applications.html).

This will bundle the output into a single executable file. Requires Node.js 25.7.0 or later (in practice Node.js 26+, since tsdown itself does not support Node.js 25), and is not supported in Bun or Deno. Cross-platform builds are supported via the `@tsdown/exe` package.

When `exe` is enabled:

* Declaration file generation (`dts`) is disabled by default.
* Code splitting is disabled.
* Only single entry points are supported.

See also [Executable](../options/exe.md).

## `-W, --workspace [dir]`

Enable workspace mode for building multiple packages in a monorepo. Optionally specify the workspace root directory.

## `--concurrency <count>`

Maximum number of Rolldown builds to run in parallel. Defaults to unlimited. Not supported in watch mode, where it is ignored.

## `-F, --filter <pattern>`

Filter configs by working directory or name. Supports string matching and regex patterns (e.g., `/pkg-name$/` or `pkg-name`).

## `--unbundle`

Enable unbundle (bundleless) mode. Each source file is compiled individually, preserving the source directory structure in the output.

See also [Unbundle](../options/unbundle.md).

## `--fail-on-warn`

Fail the build when warnings are encountered. Enabled by default.

See also [CI Environment](../advanced/ci.md).

## `--no-write`

Disable writing output files to disk. Incompatible with watch mode.

## `--exports`

Generate the `exports` field in your `package.json`.

See also [Package Exports](../options/package-exports.md).