Tailwind CLI Installation

Purpose and Scope

Use the Tailwind CLI installation path when you want Tailwind CSS to be a direct build step that reads an input stylesheet and writes a static output file. The official documentation presents this route as the simplest way to start from scratch: install the core framework package and the CLI package, import Tailwind in your CSS, run the CLI in watch mode, then link the generated CSS from your HTML. This page focuses on that workflow and on how the repository packages support it, so readers can distinguish the CLI path from Vite, PostCSS, Webpack, framework integrations, and the browser runtime.

The important mental model is that the CLI is not a separate styling engine. It is a command-line front door to the same Tailwind compiler surface used by the other first-party integrations. The executable parses terminal arguments and dispatches build work, while the core package supplies CSS entry points, compiler types, import substitution, theme parsing, plugin compatibility hooks, and utility generation. That separation is useful when troubleshooting: command syntax problems belong near the CLI entry point, while import resolution, theme directives, plugins, and generated utilities are handled deeper in the compiler pipeline. Sources: packages/@tailwindcss-cli/src/index.ts, packages/tailwindcss/src/index.ts, packages/tailwindcss/package.json

Relevant Source Files

• packages/@tailwindcss-cli/src/index.ts — CLI executable entry point; defines root help, build usage text, dispatch for the default build command, explicit build subcommand, and canonicalize command.
• packages/tailwindcss/src/index.ts — Core compiler surface; defines compile options, feature flags, CSS parsing support, import substitution, module and stylesheet loading hooks, theme handling, and compatibility behavior.
• packages/tailwindcss/package.json — Published core package metadata; exposes the main style entry and CSS subpaths for index, preflight, theme, and utilities files consumed by import-based setup.
• packages/@tailwindcss-node/src/index.ts — Node runtime barrel; re-exports compile, optimize, source-map, instrumentation, path-normalization, environment helpers, and ESM cache-loader registration behavior.
• packages/@tailwindcss-browser/src/index.ts — Browser runtime comparison point; creates a compiler from page styles, injects the default Tailwind import when appropriate, and rebuilds from observed style tags.
• package.json — Monorepo-level workspace scripts and tooling; shows that local development, testing, builds, integration tests, and playgrounds are coordinated across packages.

Installation Flow

A minimal CLI setup has four user-facing steps. First, install the framework and the CLI package in the project where you want to produce CSS. Second, create an input stylesheet that imports Tailwind. Third, run the CLI with an input path, output path, and optional watch mode so the command can scan project sources and regenerate CSS while you work. Fourth, include the output file in the page or application shell and start using utility classes in markup. The generated stylesheet is the deliverable, which is why this path fits simple sites and custom build scripts well.

npm install tailwindcss @tailwindcss/cli

@import "tailwindcss";

npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch

The official command uses short flags, but the repository entry point describes the same operation with build usage text shaped around an input stylesheet, an output stylesheet, watch mode, and additional options. The executable supports both a compact root form and an explicit build subcommand. That means a package script can choose readability over brevity without changing the conceptual workflow. For example, a tutorial might use the compact command, while a long-lived project script can say build explicitly so future maintainers can see that Tailwind is being run as a CSS build step. Sources: packages/@tailwindcss-cli/src/index.ts

npx @tailwindcss/cli --input ./src/input.css --output ./src/output.css --watch
npx @tailwindcss/cli build --input ./src/input.css --output ./src/output.css --watch
npx @tailwindcss/cli --help

Core Primitives

The first primitive is the input stylesheet. In Tailwind v4, a normal starting point is an import of the framework package, which works because the core package treats CSS files as public package entries. Its package metadata exposes the main style entry plus direct subpaths for the index, preflight, theme, and utilities stylesheets. This matters for CLI users because the import in the input file is not a magic string owned only by the command. It resolves through the published framework package contract that other integrations can also rely on. Sources: packages/tailwindcss/package.json

The second primitive is the compiler. The core TypeScript entry defines compile options with a base path, source filename, polyfill selection, a module-loading hook for plugins and configuration, and a stylesheet-loading hook for imports. Its parsing flow tracks features such as imports, plugin or config compatibility, theme functions, utilities, variants, and theme directives. CLI users normally interact only with command flags and CSS files, but the output they receive depends on this compiler contract. When a build behaves unexpectedly, check whether the input CSS, import graph, theme directives, or plugin configuration are giving the compiler the information it needs. Sources: packages/tailwindcss/src/index.ts

The third primitive is the Node execution environment. The Node package re-exports compilation, optimization, instrumentation, source-map, path-normalization, and environment utilities, and it registers module-resolution hooks when the current Node runtime supports them and the process is not Bun. This support layer is relevant because CLI builds run outside the browser and may need to load JavaScript configuration, plugins, dependencies, and source maps from local files. It also explains why the CLI installation path is different from the Play CDN path even though both ultimately create a Tailwind compiler. Sources: packages/@tailwindcss-node/src/index.ts

Command Dispatch and Edge Cases

The CLI executable starts with a Node shebang, reads process arguments, and chooses a command. If the first argument is build, it parses build-specific options, prints build-level help when appropriate, and delegates to the build handler. If the first argument is canonicalize, it runs the canonicalization command-line path and writes any captured standard output or standard error before propagating the exit code. If no subcommand is provided, the root executable still behaves like the build command unless help should be shown for an interactive terminal or a help flag was supplied. Sources: packages/@tailwindcss-cli/src/index.ts

There are a few practical edge cases worth knowing before you put the CLI in project scripts. Passing an unknown word as the first argument is treated as an invalid command, so the executable prints root help and exits with an error instead of quietly interpreting the word as a build option. Invoking the command with help at the root level prints root usage that lists both build and canonicalize forms. Invoking help for the build subcommand prints build-specific usage. This behavior makes mistakes visible in continuous integration and keeps documentation examples aligned with the command dispatcher. Sources: packages/@tailwindcss-cli/src/index.ts

Source-to-Code Mapping

The installation task maps cleanly to repository responsibilities. The user installs the published framework package because it owns the CSS exports and compiler surface. The user installs the CLI package because it owns terminal argument parsing and command dispatch. The input CSS import resolves through the framework package exports. The build command then relies on compiler behavior to parse CSS, load stylesheets, apply compatibility hooks, expand theme information, and generate utilities from detected class candidates. The monorepo root coordinates development of these packages with shared build, lint, test, integration-test, and playground scripts. Sources: package.json, packages/tailwindcss/package.json, packages/tailwindcss/src/index.ts

The browser runtime is useful as a contrast, not as a replacement for local CLI builds. It scans page style tags with the Tailwind-specific style type, concatenates their contents, injects a default Tailwind import when no import is present, creates a compiler with a browser base path, and maps supported package imports to bundled virtual assets. It also queues browser builds and tracks classes already seen on the page. CLI builds instead start from a filesystem input file and write a filesystem output file, which is better for production artifacts, static hosting, and repeatable scripts. Sources: packages/@tailwindcss-browser/src/index.ts

Local Development and Verification Signals

Inside the Tailwind repository, CLI installation behavior is maintained alongside the rest of the monorepo rather than in isolation. The root package uses pnpm as the package manager and Turbo for cross-package build, development, and lint workflows. It also declares commands for Rust tests, Vitest suites, integration tests, UI tests, benchmarks, package versioning, and playground development. That organization is a signal for contributors: a change that appears to affect only the CLI may still need validation against the core package exports, compiler behavior, Node helpers, integrations, and browser runtime comparisons. Sources: package.json

The core framework package adds another verification layer because it declares its own lint, build, development, and UI test scripts as well as the files that are published. If a CLI-based installation stops resolving the standard import, inspect the framework export map and files list before looking for a command-line parsing problem. If output changes after compiler work, inspect the compiler entry point and the Node runtime support layer. Good local checks follow the dependency direction: command invocation first, package export resolution second, compiler behavior third, and integration or playground behavior last. Sources: packages/tailwindcss/package.json, packages/tailwindcss/src/index.ts, packages/@tailwindcss-node/src/index.ts

Choosing the CLI Path

Choose the CLI path when you own the CSS input and want an explicit output stylesheet that can be linked from HTML, copied into a static site, or managed by a small custom script. Choose Vite, PostCSS, Webpack, or a framework guide when Tailwind should participate in an existing bundler or application pipeline. Choose the browser runtime or Play CDN for quick in-page experiments where installing Node packages and writing output files is not the goal. After completing this installation path, read the CLI reference for command details, the package API page for compiler behavior, and the class detection page for how source scanning feeds generated CSS.