{"id":18950353,"url":"https://github.com/clay/claycli","last_synced_at":"2026-02-19T04:31:11.275Z","repository":{"id":21047740,"uuid":"91127497","full_name":"clay/claycli","owner":"clay","description":"A CLI For Clay!","archived":false,"fork":false,"pushed_at":"2025-06-02T14:12:39.000Z","size":6595,"stargazers_count":16,"open_issues_count":37,"forks_count":12,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-10-26T13:57:02.199Z","etag":null,"topics":["clay","cli","javascript"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-05-12T20:31:07.000Z","updated_at":"2025-10-06T09:01:33.000Z","dependencies_parsed_at":"2024-04-16T20:41:18.484Z","dependency_job_id":"cd739094-8f26-46d8-b05a-052e74ef5d68","html_url":"https://github.com/clay/claycli","commit_stats":null,"previous_names":["nymag/clay-cli"],"tags_count":74,"template":false,"template_full_name":null,"purl":"pkg:github/clay/claycli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clay%2Fclaycli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clay%2Fclaycli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clay%2Fclaycli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clay%2Fclaycli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clay","download_url":"https://codeload.github.com/clay/claycli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clay%2Fclaycli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29603042,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T04:01:40.476Z","status":"ssl_error","status_checked_at":"2026-02-19T04:01:12.960Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clay","cli","javascript"],"created_at":"2024-11-08T13:22:35.378Z","updated_at":"2026-02-19T04:31:11.258Z","avatar_url":"https://github.com/clay.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claycli\nA CLI For Clay!\n\n[![CircleCI](https://circleci.com/gh/clay/claycli.svg?style=svg)](https://circleci.com/gh/clay/claycli) [![Coverage Status](https://coveralls.io/repos/github/clay/claycli/badge.svg?branch=master)](https://coveralls.io/github/clay/claycli?branch=master)\n\n# Installation\n\n```\nnpm install -g claycli\n```\n\n# Usage\n\n```\nclay \u003ccommand\u003e [options]\n```\n\nIf installed globally, call `clay` from the command line. Much like `git`, `claycli` is configured using a [dotfile](https://medium.com/@webprolific/getting-started-with-dotfiles-43c3602fd789) (`.clayconfig`) in your home folder. In it you may specify references to api keys and urls / site prefixes that you use frequently. For urls and site prefixes, it will assume `http://` and port `80` unless you specify otherwise.\n\nNote that a _site prefix_ is everything before the api route, e.g. `http://domain.com/site1` in `http://domain.com/site1/_components/article`.\n\n```\n[keys]\n  local=ha8yds9a8shdf98asdf\n  qa=8quwqwer09ewr0w9uer\n  prod=bj34b6345k634jnk63n4\n[urls]\n  local-site1=https://localhost.site1.com:3001\n  local-site2=site2.com/site-2 # http and port 80\n```\n\nFor smaller Clay installations (or, ironically, for very large teams where devs spend most of their time on individual sites), you may specify a default api key and url / site prefix by using the `CLAYCLI_DEFAULT_KEY` and `CLAYCLI_DEFAULT_URL` environment variables.\n\n# Commands\n\n* [`config`](https://github.com/clay/claycli#config)\n* [`lint`](https://github.com/clay/claycli#lint)\n* [`import`](https://github.com/clay/claycli#import)\n* [`export`](https://github.com/clay/claycli#export)\n* [`compile`](https://github.com/clay/claycli#compile)\n\n## Common Arguments\n\n`claycli` uses some common arguments across many commands.\n\n* `-v, --version` will print the `claycli` version and exit\n* `-h, --help` will print helpful info about `claycli` and exit\n* `-r, --reporter` allows specifying how results should be logged\n* `-c, --concurrency` allows setting the concurrency of api calls (defaults to 10)\n* `-k, --key` allows specifying an api key or alias\n\n### Logging\n\nWhen running `claycli` programmatically (i.e., `import { someMethod } from 'claycli'`), most commands will return a stream of objects with `{ type, message, details }`. The `type` may be `success` (signalling that an operation succeeded), `error`, `warning`, `info`, or `debug`. As you can see, most of those correspond directly to log levels.\n\nWhen running `claycli` from the command line, you may specify a `reporter` argument to output logs in different formats. The default is `dots`, which will print out green and red dots showing operation success / failure. There is also `pretty` (which prints more detailed messages on each line), `json` (which prints newline-separated json logs in a format that can be passed to ELK), and `nyan` (which is mostly just for fun).\n\n```bash\nclay lint --reporter pretty domain.com/_components/article\n```\n\nYou may also specify which reporter to use by setting the `CLAYCLI_REPORTER` environment variable. If you add a `reporter` argument, it will be used instead of the env variable.\n\n```bash\nexport CLAYCLI_REPORTER=json\n```\n\n`claycli` pipes to `stderr`. If you want to pipe the logs to a file, you may use `2\u003e`.\n\n```bash\n`clay lint --reporter json domain.com/_components/article 2\u003e article-log.json`\n```\n\n## Handling Files\n\n### Dispatch\n\nMany `claycli` commands allow you to pipe in the contents of files to `stdin` or pipe data out from `stdout`. The format that `claycli` uses to represent data (similar to a database dump) is called a _dispatch_, and it consists of newline-separated JSON without site prefixes.\n\n```\n{\"/_components/article/instances/123\":{\"title\":\"My Article\",\"content\":[{\"_ref\":\"/_components/paragraph/instances/234\",\"text\":\"Four score and seven years ago...\"}]}}\n{\"/_components/meta-title/instances/345\":{\"title\":\"My Article\",\"ogTitle\":\"My Longer Titled Article\",\"twitterTitle\":\"Article\"}}\n```\n\nEach line of a _dispatch_ contains [composed data for a component](https://github.com/clay/amphora/blob/master/lib/routes/readme.md#component-data) (or page, user, list, etc), including any data for its child components. This means that each line is able to be sent as a [cascading PUT](https://github.com/clay/amphora/pull/73) to the Clay server, which is a highly efficient way of importing large amounts of data. Note that a _dispatch_ is not meant to be human-readable, and manually editing it is a very easy way to introduce data errors.\n\nA _dispatch_ may be piped into or out of commands such as `clay import` and `clay export`. Because _dispatches_ are a special format (rather than regular JSON files), the convention is to use the `.clay` extension, but this isn't required.\n\n```bash\nclay export domain.com \u003e article_dump.clay\nclay import domain.com \u003c article_dump.clay\nclay export domain.com | clay import localhost\n```\n\n### Bootstrap\n\nFor working with human-readable data, we use a format called a _bootstrap_. These are human-readable [yaml](http://docs.ansible.com/ansible/latest/YAMLSyntax.html) files that divide components (and pages, users, lists, etc) by type. [This is the same format that is used by the `bootstrap.yml` files in your Clay install](http://clay.github.io/amphora/docs/lifecycle/startup/bootstrap.html).\n\n```yaml\n_components:\n  article:\n    instances:\n      123:\n        title: My Article\n        content:\n          - _ref: /_components/paragraph/instances/234\n  paragraph:\n    instances:\n      234:\n        text: Four score and seven years ago...\n  meta-title:\n    instances:\n      345:\n        title: My Article\n        ogTitle: My Longer Titled Article\n        twitterTitle: Article\n```\n\nA _bootstrap_ may be piped into and out of any `claycli` commands that accept _dispatches_. To tell `claycli` that you're dealing with _bootstraps_, please use the `--yaml` argument.\n\n```bash\nclay export --yaml domain.com \u003e article_dump.yml\nclay import --yaml domain.com \u003c article_dump.yml\n```\n\nIf you're a backend developer or database architect, it may be helpful to think of _dispatches_ and _bootstraps_ as [denormalized and normalized data](https://medium.com/@katedoesdev/normalized-vs-denormalized-databases-210e1d67927d). You'll notice that the two examples above contain the same data. The denormalized _dispatches_ allow a single API call per line and use less memory because they're streamable, while the normalized _bootstraps_ are better for hand-coding data because components are not duplicated if referenced multiple times. Generally speaking, use _dispatches_ for transporting and storing data and _bootstraps_ for hand-coding.\n\n## Config\n\n```bash\nclay config --key \u003calias\u003e [value]\nclay config --url \u003calias\u003e [value]\n```\n\nShow or set configuration options. These are saved to `~/.clayconfig`. As specified above, sites will assume `http` and port `80` if you do not write the protocol and port.\n\n### Arguments\n\n* `-k, --key` allows viewing or saving an api key\n* `-u, --url` allows viewing or saving a url / site prefix\n* `-r, --reporter` allows specifying how results should be logged (note: all reporters except `json` report `clay config` the same)\n\n### Examples\n\n```bash\n# view all configuration options\nclay config\n\n# view 'local' api key\nclay config --key local\n\n# set 'local' api key\nclay config --key local ab27s9d\n\n# view 'qa' site prefix\nclay config --url qa\n\n# set 'qa' site prefix\nclay config --url qa https://qa.domain.com:3001\n\n# set a specific url\nclay config --url my-cool-article domain.com/_components/article/instances/123\n```\n\n## Lint\n\n```bash\nclay lint [--concurrency \u003cnumber\u003e] [url]\n```\n\nVerify Clay data against standardized conventions and make sure all child components exist.\n\nLinting a page, component, or user url will verify that the data for that url exists, and (for pages and components) will (recursively) verify that all references to child components exist. The url must be a raw url, an alias specified via `clay config`, or omitted in favor of `CLAYCLI_DEFAULT_URL`. Linting a public url (or a page/component url that has a `.html` extension) will attempt to render that url with the extension and, if that fails, try to figure out which component isn't rendering correctly. You may lint other renderers by providing their extensions, e.g. `.amp` or `.rss`.\n\nInstead of linting a url, you may pipe in a component's `schema.yml` to lint. It will go through the schema and verify that it conforms to [Kiln's schema rules](https://claycms.gitbooks.io/kiln/editing-components.html).\n\n### Arguments\n\n* `-r, --reporter` allows specifying how results should be logged\n* `-c, --concurrency` allows setting the concurrency of api calls\n\n### Examples\n\n```bash\n# lint all components on a page\nclay lint domain.com/_pages/123\n\n# lint a page via public url\nclay lint domain.com/2018/02/some-slug.html\n\n# lint a component and its html\nclay lint domain.com/_components/article/instances/abc.html\n\n# lint a component specified via config alias\nclay lint my-cool-article\n\n# lint single schema\nclay lint \u003c components/article/schema.yml\n```\n\n## Import\n\n```bash\nclay import [--key \u003capi key\u003e] [--concurrency \u003cnumber\u003e] [--publish] [--yaml] [site prefix]\n```\n\nImports data into Clay from `stdin`. Data may be in _dispatch_ or _bootstrap_ format. Site prefix must be a raw url, an alias specified via `clay config`, or omitted in favor of `CLAYCLI_DEFAULT_URL`. Key must be an alias specified via `clay config`, or omitted in favor of `CLAYCLI_DEFAULT_KEY`.\n\nThe `publish` argument will trigger a publish of the pages and / or components you're importing. Note that the generated url of an imported page might be different than its original url, depending on your Clay url generation / publishing logic.\n\n### Arguments\n\n* `-k, --key` allows specifying an api key or alias\n* `-r, --reporter` allows specifying how results should be logged\n* `-c, --concurrency` allows setting the concurrency of api calls\n* `-p, --publish` triggers publishing of imported pages\n* `-y, --yaml` specifies that input is _bootstrap_ format\n\n### Examples\n\n```bash\n# import a dispatch\nclay import --key local localhost:3001 \u003c db_dump.clay\n\n# import and publish pages in a bootstrap\nclay import --key qa --publish --yaml \u003c bootstrap.yml\n\n# pipe from 3rd party exporter\nwordpress-export domain.com/blog | clay import --key local localhost.domain.com\n\n# pipe from clay exporter\nclay export --key prod domain.com/_components/article/instances/123 | clay import --key local localhost.domain.com\n\n# import multiple dispatches\ncat *.clay | clay import --key local localhost:3001\n\n# import multiple bootstraps\ntail -n +1 *.yml | clay import --key local --yaml localhost:3001\n\n# recursively import multiple bootstraps\nfind . -name '*.yml' -exec cat \"{}\" \\; | clay import --key local --yaml localhost:3001\n\n# recursively import multiple bootstraps (bash v4+ \u0026 zsh)\ncat **/*.yml | clay import --key local --yaml localhost:3001\n```\n\n## Export\n\n```bash\nclay export [--key \u003capi key\u003e] [--concurrency \u003cnumber\u003e] [--size \u003cnumber\u003e] [--layout] [--yaml] [url]\n```\n\nExports data from Clay to `stdout`. Data may be in _dispatch_ or _bootstrap_ format. The url must be a raw url, an alias specified via `clay config`, or omitted in favor of `CLAYCLI_DEFAULT_URL`.\n\nIf the url points to a site prefix (i.e. it does not point to a specific type of data (a specific page, public url, component, user, list, etc)), `claycli` will query the built-in `pages` index to pull the latest 10 pages from the site. When querying the `pages` index, you must specify a `key` or have the `CLAYCLI_DEFAULT_KEY` set. The api key is only required when exporting multiple pages (by querying the `pages` index or by running custom queries, below).\n\nInstead of fetching the latest pages, you may pipe in a yaml-formatted [elasticsearch query](https://www.elastic.co/guide/en/elasticsearch/reference/current/_introducing_the_query_language.html). Use this to set custom offsets (for batching and chunking exports), export non-page content from other indices, or filter exported data via certain properties. Note that if you pipe in a query that includes `size`, it will take precedence over the CLI `size` argument.\n\n```yaml\nindex: pages\nsize: 100\nbody:\n  sort:\n    updateTime:\n        order: desc # sort by latest updated\n  query:\n    bool:\n      must:\n        -\n          terms:\n            siteSlug:\n              - intelligencer # show only pages for a specific site\n        -\n          match:\n            published: true # show only published pages\n\n```\n\nYou may also query other elastic indices, but please make sure that each document returned has a clay uri (e.g. `domain.com/_components/foo/instances/bar` or `domain.com/_pages/foo`) as its `_id`.\n\n```yaml\nindex: published-products\nsize: 5\nfrom: 10\nsort:\n  - price\nbody:\n  query:\n    match_all: {}\n```\n\nBy default, layouts are not exported when exporting pages. This allows you to easily copy individual pages between sites and environments. To trigger layout exporting, please use the `layout` argument.\n\n### Arguments\n\n* `-k, --key` allows specifying an api key or alias\n* `-r, --reporter` allows specifying how results should be logged\n* `-c, --concurrency` allows setting the concurrency of api calls\n* `-s, --size` specifies the number of pages to export (defaults to 10)\n* `-l, --layout` triggers exporting of layouts\n* `-y, --yaml` specifies that output is _bootstrap_ format\n\n### Examples\n\n```bash\n# export individual component\nclay export domain.com/_components/article/instances/123 \u003e article_dump.clay\n\n# export individual page\nclay export --yaml domain.com/_pages/123 \u003e page_bootstrap.yml\n\n# export page with layout\nclay export --layout --yaml domain.com/_pages/123 \u003e page_bootstrap.yml\n\n# copy page to local environment\nclay export domain.com/_pages/123 | clay import --key local local.domain.com\n\n# export latest updated page\nclay export --key prod --size 1 domain.com \u003e recent_page.clay\n\n# export custom query to dispatch\ncat query.yml | clay export --key prod domain.com \u003e db_dump.clay\n\n# export custom query to bootstrap\nclay export --yaml --key prod domain.com/sub-site \u003c query.yml \u003e pages.yml\n\n# note that 'cat query.yml | clay export' and 'clay export \u003c query.yml' are equivalent ways\n# to pipe from a file into claycli in most operating systems\n\n#\n# other things you may export\n#\n\n# export single user\nclay export domain.com/_users/abs8a7s8d --yaml \u003e my_user.yml\n\n# export all users\nclay export domain.com/_users --yaml \u003e users.yml\n\n# export single list\nclay export domain.com/_lists/tags \u003e tags.clay\n\n# export all lists\nclay export domain.com/_lists \u003e lists.clay\n\n# export published page via public url\nclay export domain.com/2017/02/some-slug.html\n\n# export built-in 'New Page Templates' list (page uris will be unprefixed)\nclay export domnain.com/_lists/new-pages\n```\n\n## Compile\n\n```bash\nclay compile [--watch] [--minify] [--inlined] [--linked] [--plugins \u003cspace-separated list of postcss plugins\u003e] [--globs \u003cspace-separated glob strings\u003e] [--reporter \u003creporter\u003e]\n```\n\nCompile assets based on standardized Clay conventions. Assets are compiled to a `public` folder at the root of your Clay install (the directory where you run the `clay compile` command), with scripts (including templates), styles (including fonts), and media output to the `js`, `css`, and `media` folders. You may run `clay compile` to compile _all_ assets, or run any of its subcommands (`media`, `fonts`, `styles`, `templates`, `scripts`) to compile a specific type of asset.\n\nSpecifying `--watch` on `claycli compile` or any of its subcommands will compile assets once, then watch source files (and their dependencies) for changes. Specifying `--minify` (or setting `CLAYCLI_COMPILE_MINIFIED`) will run assets through minification and bundling if applicable. The `CLAYCLI_COMPILE_ASSET_HOST` and `CLAYCLI_COMPILE_ASSET_PATH` variables are used by the `styles` and `fonts` subcommands to generate links to media and font files in the compiled CSS.\n\nA project specific clay config file is also supported, [read more here](https://github.com/clay/claycli#project-specific-config-file).\n\n#### Arguments\n\n* `-w, --watch` enables watching of source files after compilation\n* `-m, --minify` enables minification and bundling of source files\n* `-i, --inlined` enables the generation of base64 inlined font CSS\n* `-l, --linked` enables the generation of linked font CSS\n* `-p, --plugins` allows running additional postcss plugins when compiling styles\n* `-g, --globs` allows compiling additional JavaScript to `public/js/_global.js`\n* `-r, --reporter` allows specifying how results should be logged\n\n#### Examples\n\n```bash\n# compile all assets once\nclay compile\n\n# compile and watch all assets\nclay compile --watch\n\n# compile all assets once for production environments\nclay compile --minify\n\n# compile all assets, creating both inlined and linked font CSS\nclay compile --inlined --linked\n```\n\n### Media\n\n```bash\nclay compile media [--watch] [--reporter \u003creporter\u003e]\n```\n\nCopy component, layout, styleguide, and site-specific media files from their source folders to the `public` directory. Media files are images (`jpg`, `jpeg`, `png`, `gif`), `svgs`, and favicons (`ico`).\n\n* `components/\u003cname\u003e/media/` are referenced by component templates and get copied to `public/media/components/\u003cname\u003e/`\n* `layouts/\u003cname\u003e/media/` are referenced by layout templates and get copied to `public/media/layouts/\u003cname\u003e/`\n* `styleguides/\u003cname\u003e/media/` are referenced by that styleguide's CSS and get copied to `public/media/stylesguides/\u003cname\u003e/`\n* `sites/\u003cname\u003e/media/` are favicons and other site-specific icons that are referenced by particular components in the `\u003chead\u003e` of pages. They get copied to `public/media/sites/\u003cname\u003e/`\n\n#### Arguments\n\n* `-w, --watch` enables watching of source files after compilation\n* `-r, --reporter` allows specifying how results should be logged\n\n#### Examples\n\n```bash\n# compile media files once\nclay compile media\n\n# compile and watch media files\nclay compile media --watch\n```\n\n### Fonts\n\n```bash\nclay compile fonts [--watch] [--minify] [--inlined] [--linked] [--reporter \u003creporter\u003e]\n```\n\nCompile fonts from `styleguides/\u003cname\u003e/fonts/` to the `public` directory. By default (and if `--linked` is specified or `CLAYCLI_COMPILE_LINKED_FONTS` is set), this will generate a `public/css/_linked-fonts.\u003cname\u003e.css` file with `@font-face` declarations and copy the original font file to `public/fonts/`. Note that naming collisions are possible when using fonts of the same filename across different styleguides. If `--inlined` is specified (or `CLAYCLI_COMPILE_INLINED_FONTS` is set), this will generate a `public/css/_inlined-fonts.\u003cname\u003e.css` file with `@font-face` declarations that include a base64-encoded copy of the font.\n\n`@font-face` declarations are generated based on the filename of the original font file, with a simple convention to support various weights and styles.\n\n* `\u003cname\u003e.\u003cext\u003e` font with normal weight and style\n* `\u003cname\u003e-\u003cweight\u003e.\u003cext\u003e` or `\u003cname\u003e-\u003cstyle\u003e.\u003cext\u003e` specify a font weight _or_ style\n* `\u003cname\u003e-\u003cweight\u003e-\u003cstyle\u003e.\u003cext\u003e` specify a font weight _and_ style\n\nAll named and numbered font weights are supported, as well as the `italic` and `oblique` font styles. When referencing fonts in your CSS, use the (case-insensitive) `\u003cname\u003e` for your `font-family` rule so the `font-weight` and `font-style` rules will work as expected. Supported font extensions are `woff`, `woff2`, `otf`, and `ttf`.\n\nSpecifying `--minify` (or using `CLAYCLI_COMPILE_MINIFIED` or more specifically `CLAYCLI_COMPILE_MINIFIED_FONTS`) will run the generated font CSS through [`clean-css`](https://github.com/jakubpawlowicz/clean-css).\n\n#### Arguments\n\n* `-w, --watch` enables watching of source files after compilation\n* `-m, --minify` enables minification of font CSS\n* `-i, --inlined` enables the generation of base64 inlined font CSS\n* `-l, --linked` enables the generation of linked font CSS\n* `-r, --reporter` allows specifying how results should be logged\n\n#### Examples\n\n```bash\n# compile linked fonts\nclay compile fonts\n\n# compile inlined fonts\nclay compile fonts --inlined\n\n# compile linked and inline fonts\nclay compile fonts --inline --linked\n\n# compile fonts once for production environments\nclay compile fonts --minify\n```\n\n### Styles\n\n```bash\nclay compile styles [--watch] [--minify] [--plugins \u003cspace-separated list of postcss plugins\u003e] [--reporter \u003creporter\u003e]\n```\n\nCompile styleguide CSS files with PostCSS. Source files from `styleguides/\u003cstyleguide name\u003e/components/\u003ccomponent name\u003e.css` (and `styleguides/\u003cstyleguide name\u003e/layouts/\u003clayout name\u003e.css`) will be compiled to `public/css/\u003ccomponent or layout name\u003e.\u003cstyleguide name\u003e.css`.\n\nBy default, styles will be compiled using the [`import`](https://github.com/postcss/postcss-import), [`autoprefixer`](https://github.com/postcss/autoprefixer), [`mixins`](https://github.com/postcss/postcss-mixins), [`nested`](https://github.com/postcss/postcss-nested), and [`simple-vars`](https://github.com/postcss/postcss-simple-vars) PostCSS plugins, but you may specify additional plugins (that you have installed with `npm`) into the `--plugins` argument.\n\nSetting `CLAYCLI_COMPILE_ASSET_HOST` and `CLAYCLI_COMPILE_ASSET_PATH` will set the `$asset-host` and `$asset-path` variables, which allows linking to media hosted on other static file servers.\n\n```scss\n/* styleguides/example/components/example-component.css */\n.some-twitter-icon {\n  background-image: url('$asset-host/media/styleguides/example/twitter.svg');\n  background-size: 22px 18px;\n}\n```\n\nSpecifying `--minify` (or using `CLAYCLI_COMPILE_MINIFIED` or more specifically `CLAYCLI_COMPILE_MINIFIED_STYLES`) will run the compiled CSS through [`clean-css`](https://github.com/jakubpawlowicz/clean-css).\n\n#### Arguments\n\n* `-w, --watch` enables watching of source files and their dependencies after compilation\n* `-m, --minify` enables minification of CSS\n* `-p, --plugins` allows running additional postcss plugins\n* `-r, --reporter` allows specifying how results should be logged\n\n#### Examples\n\n```bash\n# compile css\nclay compile styles\n\n# compile and watch css and any @import'ed css files\nclay compile styles --watch\n\n# compile css with additional postcss plugins\nclay compile styles --plugins postcss-preset-env stylelint\n\n# compile styles once for production environments\nclay compile styles --minify\n```\n\n### Templates\n\n```bash\nclay compile templates [--watch] [--minify] [--reporter \u003creporter\u003e]\n```\n\nPrecompile handlebars templates so they can be used by Kiln to re-render components (and layouts) on the client side. Note that it is strongly encouraged to enable minification even in dev environments, as specifying `--minify` (or using `CLAYCLI_COMPILE_MINIFIED` or more specifically `CLAYCLI_COMPILE_MINIFIED_TEMPLATES`) will minify the compiled templates with [UglifyJS](https://github.com/mishoo/UglifyJS) and bundle the them into six files based on the component/layout name. Minifying the templates provides the best balance between file size and the number of files Kiln has to fetch on page load.\n\n* `public/js/_templates-a-d.js`\n* `public/js/_templates-e-h.js`\n* `public/js/_templates-i-l.js`\n* `public/js/_templates-m-p.js`\n* `public/js/_templates-q-t.js`\n* `public/js/_templates-u-z.js`\n\nTemplates will also be compiled to `public/js/\u003cname\u003e.template.js`.\n\n#### Arguments\n\n* `-w, --watch` enables watching of source files after compilation\n* `-m, --minify` enables bundling of precompiled templates\n* `-r, --reporter` allows specifying how results should be logged\n\n#### Examples\n\n```bash\n# precompile handlebars templates\nclay compile templates\n\n# precompile and bundle templates\nclay compile templates --minify\n\n# precompile, bundle, and watch templates\nclay compile templates --minify --watch\n```\n\n### Scripts\n\n```bash\nclay compile scripts [--watch] [--minify] [--globs \u003cspace-separated glob strings\u003e] [--reporter \u003creporter\u003e]\n```\n\nCompile component `client.js` and `model.js` files, kiln plugins, and legacy global JavaScript, while intelligently calculating and deduplicating dependencies. This generates a number of different types of files:\n\n* `public/js/\u003cname\u003e.client.js` from compiled `client.js`\n* `public/js/\u003cname\u003e.model.js` from compiled `model.js`\n* `public/js/_models-\u003cletter\u003e-\u003cletter\u003e.js` from compiled and _bundled_ `model.js`\n* `public/js/_kiln-plugins.js` from compiled kiln plugins in `services/kiln/`\n* `public/css/_kiln-plugins.css` from compiled kiln plugin styles in their `.vue` components\n* `public/js/_global.js` from compiled legacy scripts specified by the `--globs` argument\n* `public/js/\u003cnumber\u003e.js` from compiled dependencies of `client.js`, `model.js`, kiln plugin, or global scripts\n* `public/js/_deps-\u003cletter\u003e-\u003cletter\u003e.js` from compiled and bundled dependencies\n\nThis also creates a number of files that are used for instantiating component controllers, serving scripts, and speeding up incremental builds:\n\n* `public/js/_client-init.js` script that instantiates `client.js` [component controllers which export a default function](https://claycms.gitbook.io/kiln/kiln-fundamentals/components#model-and-controller)\n* `public/js/_prelude.js` dynamic bundler initialization script\n* `public/js/_postlude.js` dynamic bundler access script, adds `window.require()` which enables loading of bundled dependencies\n* `public/js/_ids.json` cache of module IDs, used when serving bundles\n* `public/js/_registry.json` cache of module dependencies, used when serving bundles\n* `client-env.json` environment variables in `model.js` and dependencies, must be added to `.gitignore` (values for these variables are [passed to Amphora via `env`](https://claycms.gitbook.io/amphora/startup/instantiation#instantiation-arguments) on server start)\n* `browserify-cache.json` local cache for fast incremental builds, must be added to `.gitignore`\n\nSpecifying `--minify` (or using `CLAYCLI_COMPILE_MINIFIED` or more specifically `CLAYCLI_COMPILE_MINIFIED_SCRIPTS`) will run all compiled scripts through [`terser`](https://github.com/fabiosantoscode/terser).\n\nThis will also copy `clay-kiln-edit.js` and `clay-kiln-view.js` to `public/js` if you have Kiln installed. When you specify `--watch`, Kiln scripts will also be watched for changes.\n\n#### Dependency Management\n\nAny files you `require()` or `import` in your `client.js`, `model.js`, kiln plugins, or legacy global JavaScript are compiled to `\u003cnumber\u003e.js` and `_deps-\u003cletter\u003e-\u003cletter\u003e.js`, based on their name (for example, `lodash` might be compiled to `283.js` and `_deps-i-l.js`). When resolving media, call `claycli.compile.scripts.getDependencies()` in your Clay install's `resolveMedia` function to dynamically load necessary dependencies for view (`client.js` and legacy `_global.js`) and edit (`model.js` and kiln plugins) modes.\n\n```js\n// in your resolve-media service\nconst getDependencies = require('claycli').compile.scripts.getDependencies;\n\n/**\n * figure out what scripts and styles should be loaded on each page\n * @param  {object} media\n * @param  {array} media.scripts array of filenames from amphora\n * @param  {array} media.styles array of filenames from amphora\n * @param  {object} locals site info, edit mode info, etc from amphora\n */\nfunction resolveMedia(media, locals) {\n  const assetPath = locals.site.assetPath; // from site config\n\n  // note: for this example, we're only dealing with scripts.\n  // your own media resolution must also take into account styles, fonts, and templates\n  if (locals.edit) {\n    // edit mode, get script dependencies for linking (so, bundled / minified files)\n    media.scripts = getDependencies(media.scripts, assetPath, { edit: true, minify: true });\n  } else {\n    // view mode, get script dependencies for inlining (so, individual dependency files)\n    media.scripts = getDependencies(media.scripts, assetPath);\n  }\n}\n```\n\nBy convention, internal services are specified in a `services/` directory at the root of your Clay install. Services that work in both the client and server live in `services/universal/` (or `services/isomorphic/` if you prefer). If you have `services/client/` and `services/server/` directories, `claycli` will automatically substitute server-side dependencies with their client-side equivalents when compiling. This is useful for database / API calls and wrappers around 3rd party libraries that have wildly different Node.js vs browser implementations.\n\n#### Kiln Plugins\n\nThis will look for kiln plugins in `services/kiln/index.js`. You may specify vuex plugins, custom inputs, toolbar buttons, and pre-publish validators, [among other things](https://claycms.gitbook.io/kiln/api-documentation/api). For example, you might have one validator, one input, and one vuex plugin:\n\n```js\n// services/kiln/index.js\nmodule.exports = () =\u003e {\n  // add globals if they don't already exist\n  window.kiln = window.kiln || {};\n  window.kiln.validators = window.kiln.validators || {};\n  window.kiln.inputs = window.kiln.inputs || {};\n  window.kiln.plugins = window.kiln.plugins || {};\n  // add your plugins into the globals\n  window.kiln.validators['unique-url'] = require('./validate-unique-url');\n  window.kiln.inputs['content-picker-button'] = require('./content-picker-button.vue');\n  window.kiln.plugins['kiln-error-tracking'] = require('./kiln-tracking-plugin');\n};\n```\n\nAny styles (denoted with `\u003cstyle lang=\"postcss\"\u003e` sections in your `.vue` components) will be extracted and bundled into `public/css/_kiln-plugins.css`, so please make sure to include it in your `resolveMedia` function in edit mode.\n\n#### Legacy Global Scripts\n\nIf you have any legacy scripts that are not `require()`'d or `import`'d by your `client.js` or their dependencies, you may specify `--globs` to include them. They will be compiled and have their dependencies dynamically deduplicated in the same way as your other scripts, but will be served in view mode on _every page_.\n\n#### Arguments\n\n* `-w, --watch` enables watching of scripts and their dependencies after compilation\n* `-m, --minify` enables minification of scripts\n* `-g, --globs` allows compiling additional JavaScript\n* `-r, --reporter` allows specifying how results should be logged\n\n#### Examples\n\n```bash\n# compile scripts once\nclay compile scripts\n\n# compile and watch scripts and dependencies\nclay compile scripts --watch\n\n# compile scripts once for production environments\nclay compile scripts --minify\n\n# compile scripts, including legacy js\n# note: this glob will match all '.js' files in 'global/js/' unless they end in '.test.js',\n# which is a common unit testing convention\nclay compile scripts --globs 'global/js/!(*.test).js'\n```\n\n### Project Specific Config File\n\nNot all projects are the same, and for project specific compilation changes you can add a `claycli.config.js` file to your project's root. This file must simply export an Object whose contains key/value pairs are read during compilation. Good use cases for this file include:\n\n* Adding PostCSS plugins to [`styles`](https://github.com/clay/claycli#styles) compilation\n* Updating options passed into Autoprefixer\n* Changing Babel browser target to meet your env support requirements\n\n#### Arguments\n\nThe `claycli.config.js` file currently supports the following arguments:\n\n* `plugins` (_Array_): list of PostCSS plugins that will be concatenated to the end of the list already supported by the `styles` compilation command\n* `babelTargets` (_Object_): the value of this property is passed to the [Babel `targets` option](https://babeljs.io/docs/en/babel-preset-env#targets) to describe the environments your compiled scripts support\n* `autoprefixerOptions` (_Object_): an Object which is [passed directly to `autoprefixer`](https://www.npmjs.com/package/autoprefixer#options) for style and Kiln plugin compilation\n* `customTasks` (_Array_): an Array of Gulp tasks to execute with the `clay compile custom-tasks` command.\n* `postcssImportPaths` (_Array_): list of paths in which to look for nested CSS file imports to be used by the `styles` compilation command. If no value is specified in the congif, the CSS compiler will default to `['./styleguides']`.\n#### Example\n\n```js\n'use strict';\n\nmodule.exports = {\n  plugins: [\n    require('postcss-functions')({\n      functions: {\n        em: function (pixels, browserContext) {\n          var browserContext = parseInt(browserContext, 10) || 16,\n            pixels = parseFloat(pixels);\n\n          return pixels / browserContext + 'em';\n        }\n      }\n    })\n  ],\n  babelTargets:  { browsers: ['\u003e 2%'] },\n  autoprefixerOptions: { browsers: ['last 2 versions', 'ie \u003e= 9', 'ios \u003e= 7', 'android \u003e= 4.4.2'] },\n  customTasks: [{\n    name: 'foobar',\n    fn: (cb) =\u003e {\n      // A gulp task to execute\n      cb();\n    }\n  }]\n};\n```\n\n### Custom Gulp Tasks\n\nBecause not every implementation of Clay is the same, not all complilation will be the same. By adding custom Gulp tasks to your `claycli.config.js` file you can execute additional compilation/processing steps with claycli. Declare a `customTasks` array in your config file with each taks being an object with two properties: `name` and `fn`. The `name` property will be the name of the step to execute and the `fn` property is the actual step to execute.\n\n#### Example\n\nFor example, given the following `claycli.config.js` file:\n\n```js\n'use strict';\n\nvar { gulp } = require('claycli'),\n  concat = require('gulp-concat'),\n  uglify = require('gulp-uglify'),\n  gutil = require('gulp-util'),\n  argv = require('yargs').argv,\n  gulpif = require('gulp-if');\n\nmodule.exports = {\n  customTasks: [\n    {\n      name: 'polyfill',\n      fn: () =\u003e {\n        return gulp.src([\n          'global/polyfills.js',\n          'global/modernizr.js'\n        ])\n        .pipe(concat('polyfills.js'))\n        .pipe(gulpif(!argv.debug, uglify())).on('error', gutil.log)\n        .pipe(gulp.dest('public/js'));\n      }\n    }\n  ]\n};\n```\n**Important Notes:**\n\n1. Claycli exposes the instance of `gulp` that it users to make sure their is consistency between internal tasks and external ones\n2. This example of a custom task is all done inline, but the objects can be organizes and managed in different files\n3. When executing commands you have access to `argv` and can test options inside your custom functions.\n4. Each task is executed in isolation. This is not a replacement for a complete Gulp pipeline, rather it is meant to patch small tasks that fall outside normal Clay compilation.\n\nExecuting `clay compile custom-tasks` will execute this task to produce a `polyfills.js` file.\n\n# Programmatic API\n\nThe core `claycli` functionality is exposed as an api, allowing you to use it in Node.js. All main commands are properties of the exported `claycli` object.\n\n```js\nconst { config, lint, import, export, compile } = require('claycli');\n```\n\n## Config\n\nGet `key` or `url` from config\n\n```js\nconfig.get(type, alias);\n```\n\nSet `key` or `url` in config\n\n```js\nconfig.set(type, alias, value);\n```\n\nGet full configuration object\n\n```js\nconfig.getAll();\n```\n\n## Lint\n\nLint a url\n\n```js\nlint.lintUrl(url, { concurrency });\n```\n\nLint a schema (passed in as a string of yaml)\n\n```js\nlint.lintSchema(yaml);\n```\n\n## Import\n\nImport a string of dispatches or bootstraps to the specified (site prefix) url\n\n```js\nimport(string, url, { key, concurrency, publish, yaml });\n```\n\nParse a string of bootstrap data into a stream of prefixed dispatches. _Note: does NOT do http calls_\n\n```js\nimport.parseBootstrap(string, url);\n```\n\nParse an object of bootstrap data into a stream of prefixes dispatches. This method is good if you want to handle converting Yaml to JSON in your own application where you might need memoization. _Note: does NOT do http calls_\n\n```js\nimport.parseBootstrapObject(obj, url);\n```\n\nParse a string of dispatches into a stream of prefixed dispatches. _Note: does NOT do http calls_\n\n```js\nimport.parseDispatch(string, url);\n```\n\n## Export\n\nExport a single url, e.g. `domain.com/_components/foo` or `domain.com/_pages`\n\n```js\nexport.fromURL(url, { concurrency, layout, yaml });\n```\n\nExport the results of a query (passed in as a string of yaml)\n\n```js\nexport.fromQuery(url, query, { key, concurrency, layout, yaml, size });\n```\n\nClear the layouts cache. when exporting pages with layouts, they'll be cached so they don't need to be exported for every page\n\n```js\nexport.clearLayouts();\n```\n\n## Compile\n\n_Note:_ There is currently no single `require('claycli').compile` method that will compile all assets. Please use the individual `media`, `fonts`, `styles`, `templates`, and `scripts` methods as needed.\n\nCompile media files\n\n```js\ncompile.media({ watch });\n```\n\nCompile fonts\n\n```js\ncompile.fonts({ minify, watch, inlined, linked });\n```\n\nCompile styles\n\n```js\ncompile.styles({ minify, watch, plugins });\n```\n\nCompile templates\n\n```js\ncompile.templates({ minify, watch });\n```\n\nCompile scripts\n\n```js\ncompile.scripts({ minify, watch, globs });\n```\n\nCalculate script dependencies. _Note:_ when calling this from `resolveMedia`, the first argument is `media.scripts`\n\n```js\ncompile.scripts.getDependencies(scripts, assetPath, { edit, minify });\n```\n\n# Contributing\n\nPull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/clay/claycli/issues/new).\n\nThis project is released under the [MIT license](https://github.com/clay/claycli/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclay%2Fclaycli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclay%2Fclaycli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclay%2Fclaycli/lists"}