A command-line interface to clean-css CSS optimization library
npm install clean-css-cli
!x86 Linux build


clean-css-cli is a command-line interface to clean-css - fast and efficient CSS optimizer for Node.js.
Previously a part of clean-css it's a separate package since clean-css 4.0.
Table of Contents
- Node.js version support
- Install
- Use
* What's new in version 5.5
* What's new in version 5.1
* What's new in version 5.0
* What's new in version 4.3
* What's new in version 4.2
* What's new in version 4.1
* What's new in version 4.0
* CLI options
* Compatibility modes
* Formatting options
* Inlining options
* Optimization levels
+ Level 0 optimizations
+ Level 1 optimizations
+ Level 2 optimizations
* As a module
- FAQ
* How to optimize multiple files?
* How to process multiple files without concatenating them into one output file?
* How to specify a custom rounding precision?
* How to rebase relative image URLs?
* How to apply level 1 & 2 optimizations at the same time?
- Contributing
* How to get started?
- License
clean-css-cli requires Node.js 10.0+ (tested on Linux)
``shell`
npm install clean-css-cli -g
Note: Global install via -g option is recommended unless you want to execute the binary via a relative path, i.e. ./node_modules/.bin/cleancss
`shell`
cleancss -o one.min.css one.css
clean-css-cli 5.5 introduces the following changes / features:
* adds a new --watch switch, which makes cleancss re-run optimizations when watched file(s) change.
clean-css-cli 5.1 introduces the following changes / features:
* accept !path/to/file as a way of telling cleancss to ignore such file, also accepts any available glob patterns.
clean-css-cli 5.0 introduces the following changes / features:
* adds --batch option (off by default) which processes input files one by one without joining them together;--batch-suffix
* adds option to specify what gets appended to output filename in batch mode;--skip-rebase
* automatically creates missing output directories;
* clean-css 5.0 with loads of bugfixes;
* drops official support for Node.js 4, 6, and 8;
* option has been removed as rebasing URLs is disabled by default now--with-rebase
* option is added if you really want URLs rebasing
clean-css-cli 4.3 introduces the following changes / features:
* --input-source-map option which accepts a path to input source map file.
clean-css-cli 4.2 introduces the following changes / features:
* clean-css 4.2 as a dependency;
clean-css-cli 4.1 introduces the following changes / features:
* clean-css 4.1 as a dependency;
* --remove-inlined-files option for removing files inlined in @import statements;--compatibility selectors.mergeLimit=512
* adds glob pattern matching to source paths, see example;
* allows non-boolean compatibility options, e.g. ;beforeMinify
* extracts CLI into an importable module, so it can be reused and enhanced if needed;
* adds callback as a second argument to CLI module, see example use case.
clean-css-cli 4.0 introduces some breaking changes:
* API and CLI interfaces are split, so CLI has been moved to this repository while API stays at clean-css;
* --root and --relativeTo options are replaced by a single option taken from --output path - this means that rebasing URLs and import inlining is much simpler but may not be (YMMV) as powerful as in 3.x;--rounding-precision
* is disabled by default;--rounding-precision
* applies to all units now, not only px as in 3.x;--skip-import
* and --skip-import-from are merged into --inline option which defaults to local. Remote @import rules are NOT inlined by default anymore;--timeout
* renames option to --inline-timeout;//fonts.googleapis.com/css?family=Domine:700
* remote resources without a protocol, e.g. , are not inlined anymore;--compatibility ie9
* changes default Internet Explorer compatibility from 9+ to 10+, to revert the old default use option;--rounding-precision
* moves , --s0, and --s1 options to level 1 optimization options, see examples;--skip-media-merging
* moves , --skip-restructuring, --semantic-merging, and --skip-shorthand-compacting to level 2 optimizations options, see examples below;--keep-breaks
* level 1 optimizations are the new default, up to 3.x it was level 2;
* option is replaced with --format keep-breaks to ease transition;--skip-aggressive-merging
* option is removed as aggressive merging is replaced by smarter override merging.
`shell1
-b, --batch If enabled, optimizes input files one by one instead of joining them together
-c, --compatibility [ie7|ie8] Force compatibility mode (see Readme for advanced examples)
-d, --debug Shows debug information (minification time & compression efficiency)
-f, --format
-h, --help output usage information
-o, --output [output-file] Use [output-file] as output instead of STDOUT
-O , IMPORTANT: the prefix is O (a capital o letter), NOT a 0 (zero, a number)local
-v, --version output the version number
--inline [rules] Enables inlining for listed sources (defaults to )@import
--inline-timeout [seconds] Per connection timeout when fetching remote stylesheets (defaults to 5 seconds)
--input-source-map [file] Specifies the path of the input source map file
--remove-inlined-files Remove files inlined in statements`
--source-map Enables building input's source map
--source-map-inline-sources Enables inlining sources inside source maps
--with-rebase Enables URLs rebasing
There is a certain number of compatibility mode shortcuts, namely:
--compatibility '' (default) - Internet Explorer 10+ compatibility mode--compatibility ie9
* - Internet Explorer 9+ compatibility mode--compatibility ie8
* - Internet Explorer 8+ compatibility mode--compatibility ie7
* - Internet Explorer 7+ compatibility mode
Each of these modes is an alias to a fine grained configuration, with the following options available:
`shellrgba()
cleancss --compatibility '*,-properties.urlQuotes'
cleancss --compatibility '*,+properties.ieBangHack,+properties.ieFilters'[+-]colors.opacity controls
/ hsla() color support; defaults to on (+)on[+-]properties.backgroundClipMerging controls background-clip merging into shorthand; defaults to
(+)on[+-]properties.backgroundOriginMerging controls background-origin merging into shorthand; defaults to
(+)on[+-]properties.backgroundSizeMerging controls background-size merging into shorthand; defaults to
(+)on[+-]properties.colors controls color optimizations; defaults to
(+)off[+-]properties.ieBangHack controls keeping IE bang hack; defaults to
(-)filter[+-]properties.ieFilters controls keeping IE
/ -ms-filter; defaults to off (-)off[+-]properties.iePrefixHack controls keeping IE prefix hack; defaults to
(-)off[+-]properties.ieSuffixHack controls keeping IE suffix hack; defaults to
(-)on[+-]properties.merging controls property merging based on understandability; defaults to
(+)pc[+-]properties.shorterLengthUnits controls shortening pixel units into
, pt, or in units; defaults to off (-)url() no-repeat[+-]properties.spaceAfterClosingBrace controls keeping space after closing brace -
cleancss --compatibility '*,into url('roperties.no-repeat; defaults to on (+)url()[+-]properties.urlQuotes controls keeping quoting inside
; defaults to off (-)0[+-]properties.zeroUnitsf units
value; defaults to on (+)nav[+-]selectors.adjacentSpace controls extra space before
element; defaults to off (-)*+html...[+-]selectors.ie7Hack controls removal of IE7 selector hacks, e.g.
; defaults to on (+)ch[+-]units.ch controls treating
as a supported unit; defaults to on (+)in[+-]units.in controls treating
as a supported unit; defaults to on (+)pc[+-]units.pc controls treating
as a supported unit; defaults to on (+)pt[+-]units.pt controls treating
as a supported unit; defaults to on (+)rem[+-]units.rem controls treating
as a supported unit; defaults to on (+)vh[+-]units.vh controls treating
as a supported unit; defaults to on (+)vm[+-]units.vm controls treating
as a supported unit; defaults to on (+)vmax[+-]units.vmax controls treating
as a supported unit; defaults to on (+)vmin[+-]units.vmin controls treating
as a supported unit; defaults to on (+)`
You can also chain more rules after a shortcut when setting a compatibility:
`shell`
cleancss --compatibility 'ie9,-colors.opacity,-units.rem' one.css
The --format option accept the following options:
`shellbreaks
cleancss --format beautify one.css
cleancss --format keep-breaks one.css
cleancss --format 'indentBy:1;indentWith:tab' one.css
cleancss --format 'breaks:afterBlockBegins=on;spaces:aroundSelectorRelation=on' one.css controls where to insert breaksafterAtRule
controls if a line break comes after an at-rule; e.g. @charset; defaults to off (alias to false)afterBlockBegins
controls if a line break comes after a block begins; e.g. @media; defaults to offafterBlockEnds
controls if a line break comes after a block ends, defaults to offafterComment
controls if a line break comes after a comment; defaults to offafterProperty
controls if a line break comes after a property; defaults to offafterRuleBegins
controls if a line break comes after a rule begins; defaults to offafterRuleEnds
controls if a line break comes after a rule ends; defaults to offbeforeBlockEnds
controls if a line break comes before a block ends; defaults to offbetweenSelectors
controls if a line break comes between selectors; defaults to offbreakWith controls the new line character, can be windows or unix (aliased via crlf and lf); defaults to system one, so former on Windows and latter on UnixindentBy controls number of characters to indent with; defaults to 0indentWith controls a character to indent with, can be space or tab; defaults to spacespaces controls where to insert spacesaroundSelectorRelation
controls if spaces come around selector relations; e.g. div > a; defaults to offbeforeBlockBegins
controls if a space comes before a block begins; e.g. .block {; defaults to offbeforeValue
controls if a space comes before a value; e.g. width: 1rem; defaults to offwrapAt controls maximum line length; defaults to off`
--inline option whitelists which @import rules will be processed, e.g.
`shell`
cleancss --inline local one.css # default
`shell`
cleancss --inline all # same as local,remote
`shell`
cleancss --inline local,mydomain.example.com one.css
`shell`
cleancss --inline 'local,remote,!fonts.googleapis.com' one.css
The -O option can be either 0, 1 (default), or 2, e.g.
`shell`
cleancss -O2 one.css
or a fine-grained configuration given via a string.
Please note that level 1 optimization options are generally safe while level 2 optimizations should be safe for most users.
Important: The -O option is using the capital letter O (as in "Oscar"), not the number zero.
Level 0 optimizations simply means "no optimizations". Use it when you'd like to inline imports and / or rebase URLs but skip everything else, e.g.
`shell`
cleancss -O0 one.css
Level 1 optimizations (default) operate on single properties only, e.g. can remove units when not required, turn rgb colors to a shorter hex representation, remove comments, etc
Here is a full list of available options:
`shellcleanupCharsets
cleancss -O1 one.css
cleancss -O1 removeQuotes:off;roundingPrecision:4;specialComments:1 one.css controls @charset moving to the front of a stylesheet; defaults to onnormalizeUrls controls URL normalzation; default to onoptimizeBackground controls background property optimizatons; defaults to onoptimizeBorderRadius controls border-radius property optimizatons; defaults to onoptimizeFilter controls filter property optimizatons; defaults to onoptimizeFontWeight controls font-weight property optimizatons; defaults to onoptimizeOutline controls outline property optimizatons; defaults to onremoveEmpty controls removing empty rules and nested blocks; defaults to on (since 4.1.0)removeNegativePaddings controls removing negative paddings; defaults to onremoveQuotes controls removing quotes when unnecessary; defaults to onremoveWhitespace controls removing unused whitespace; defaults to onreplaceMultipleZeros contols removing redundant zeros; defaults to onreplaceTimeUnits controls replacing time units with shorter values; defaults to on
replaceZeroUnits controls replacing zero values with units; defaults to onroundingPrecision rounds pixel values to N decimal places; off disables rounding; defaults to offselectorsSortingMethod denotes selector sorting method; can be natural or standard; defaults to standardspecialComments denotes a number of /! ... / comments preserved; defaults to alltidyAtRules controls at-rules (e.g. @charset, @import) optimizing; defaults to ontidyBlockScopes controls block scopes (e.g. @media) optimizing; defaults to ontidySelectors controls selectors optimizing; defaults to onThere is an
all shortcut for toggling all options at the same time, e.g.`shell
cleancss -O1 'all:off;tidySelectors:on' one.css
`$3
Level 2 optimizations operate at rules or multiple properties level, e.g. can remove duplicate rules, remove properties redefined further down a stylesheet, or restructure rules by moving them around.
Please note that if level 2 optimizations are turned on then, unless explicitely disabled, level 1 optimizations are applied as well.
Here is a full list of available options:
`shell
cleancss -O2 one.css
cleancss -O2 mergeMedia:off;restructureRules:off;mergeSemantically:on;mergeIntoShorthands:off one.css
mergeAdjacentRules controls adjacent rules merging; defaults to on
mergeIntoShorthands controls merging properties into shorthands; defaults to on
mergeMedia controls @media merging; defaults to on
mergeNonAdjacentRules controls non-adjacent rule merging; defaults to on
mergeSemantically controls semantic merging; defaults to off
overrideProperties controls property overriding based on understandability; defaults to on
reduceNonAdjacentRules controls non-adjacent rule reducing; defaults to on
removeDuplicateFontRules controls duplicate @font-face removing; defaults to on
removeDuplicateMediaBlocks controls duplicate @media removing; defaults to on
removeDuplicateRules controls duplicate rules removing; defaults to on
removeEmpty controls removing empty rules and nested blocks; defaults to on (since 4.1.0)
removeUnusedAtRules controls unused at rule removing; defaults to off (since 4.1.0)
restructureRules controls rule restructuring; defaults to off
skipProperties controls which properties won\'t be optimized, defaults to empty list which means all will be optimized (since 4.1.0)
`There is an
all shortcut for toggling all options at the same time, e.g.`shell
cleancss -O2 'all:off;removeDuplicateRules:on' one.css
`As a module
clean-css-cli can also be used as a module in a way of enhancing its functionality in a programmatic way, e.g.
`js
#!/usr/bin/env nodevar cleanCssCli = require('clean-css-cli');
var customPlugin = {
level1: {
value: function (propertyName, propertyValue, options) {
if (propertyName == 'background-image' && propertyValue.indexOf('../valid/path/to') == -1) {
return propertyValue.replace('url(', 'url(../valid/path/to/');
} else {
return propertyValue;
}
}
}
}
return cleanCssCli(process, function (cleanCss) {
cleanCss.options.plugins.level1Value.push(customPlugin.level1.value);
});
`FAQ
More answers can be found in clean-css FAQ section.
How to optimize multiple files?
It can be done by passing in paths to multiple files, e.g.
`shell
cleancss -o merged.min.css one.css two.css three.css
`Since version 4.1.0 it can also be done using glob pattern matching, e.g.
`shell
cleancss -o merged.min.css *.css
`How to process multiple files without concatenating them into one output file?
Since clean-css-cli 5.0 you can optimize files one by one, without joining them into one output file, e.g.
`shell
cleancss --batch styles/*.css
`By default it will pick up every single file from
styles directory, optimize it, add a -min suffix to filename (before extension), and write it to disk.You can use
--batch-suffix option to customize the -min suffix, e.g.`shell
cleancss --batch --batch-suffix '.min' styles/*.css # output will have .min suffix before .css, e.g. styles.min.css
`or
`shell
cleancss --batch --batch-suffix '' styles/*.css # output files will OVERRIDE input files
`Remember you can use glob matching to match exactly the files you want.
Since clean-css-cli 5.1 you can also use a negated pattern to exclude some files from being matched, e.g.
`shell
cleancss --batch styles/.css !styles/.min.css
`How to specify a custom rounding precision?
The level 1
roundingPrecision optimization option accept a string with per-unit rounding precision settings, e.g.`shell
cleancss -O1 roundingPrecision:all=3,px=5
`which sets all units rounding precision to 3 digits except
px unit precision of 5 digits.How to rebase relative image URLs?
clean-css-cli will rebase paths it automatically for you when full paths to input files are passed, and
--with-rebase & --output options are used, e.g`css
/! one.css /
a {
background:url(image.png)
}
``shell
cleancss --with-rebase -o build/one.min.css one.css
``css
/! build/one.min.css /
a{background:url(../image.png)}
`How to apply level 1 & 2 optimizations at the same time?
Using
-O option twice and specifying optimization options in each, e.g.`shell
cleancss -O1 all:on,normalizeUrls:off -O2 restructureRules:on one.css
`will apply level 1 optimizations, except url normalization, and default level 2 optimizations with rule restructuring.
Contributing
See CONTRIBUTING.md.
How to get started?
First clone the sources:
`shell
git clone git@github.com:clean-css/clean-css-cli.git
`then install dependencies:
`shell
cd clean-css-cli
npm install
`then use any of the following commands to verify your copy:
`shell
npm run check # to lint JS sources with JSHint
npm test # to run all tests
``clean-css-cli is released under the MIT License.