Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/clay/claycli

A CLI For Clay!
https://github.com/clay/claycli

clay cli javascript

Last synced: 9 months ago
JSON representation

A CLI For Clay!

Awesome Lists containing this project

README 

          
# claycli

A CLI For Clay!



[![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)



# Installation



```

npm install -g claycli

```



# Usage



```

clay  [options]

```



If 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.



Note that a _site prefix_ is everything before the api route, e.g. `http://domain.com/site1` in `http://domain.com/site1/_components/article`.



```

[keys]

  local=ha8yds9a8shdf98asdf

  qa=8quwqwer09ewr0w9uer

  prod=bj34b6345k634jnk63n4

[urls]

  local-site1=https://localhost.site1.com:3001

  local-site2=site2.com/site-2 # http and port 80

```



For 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.



# Commands



* [`config`](https://github.com/clay/claycli#config)

* [`lint`](https://github.com/clay/claycli#lint)

* [`import`](https://github.com/clay/claycli#import)

* [`export`](https://github.com/clay/claycli#export)

* [`compile`](https://github.com/clay/claycli#compile)



## Common Arguments



`claycli` uses some common arguments across many commands.



* `-v, --version` will print the `claycli` version and exit

* `-h, --help` will print helpful info about `claycli` and exit

* `-r, --reporter` allows specifying how results should be logged

* `-c, --concurrency` allows setting the concurrency of api calls (defaults to 10)

* `-k, --key` allows specifying an api key or alias



### Logging



When 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.



When 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).



```bash

clay lint --reporter pretty domain.com/_components/article

```



You 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.



```bash

export CLAYCLI_REPORTER=json

```



`claycli` pipes to `stderr`. If you want to pipe the logs to a file, you may use `2>`.



```bash

`clay lint --reporter json domain.com/_components/article 2> article-log.json`

```



## Handling Files



### Dispatch



Many `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.



```

{"/_components/article/instances/123":{"title":"My Article","content":[{"_ref":"/_components/paragraph/instances/234","text":"Four score and seven years ago..."}]}}

{"/_components/meta-title/instances/345":{"title":"My Article","ogTitle":"My Longer Titled Article","twitterTitle":"Article"}}

```



Each 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.



A _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.



```bash

clay export domain.com > article_dump.clay

clay import domain.com < article_dump.clay

clay export domain.com | clay import localhost

```



### Bootstrap



For 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).



```yaml

_components:

  article:

    instances:

      123:

        title: My Article

        content:

          - _ref: /_components/paragraph/instances/234

  paragraph:

    instances:

      234:

        text: Four score and seven years ago...

  meta-title:

    instances:

      345:

        title: My Article

        ogTitle: My Longer Titled Article

        twitterTitle: Article

```



A _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.



```bash

clay export --yaml domain.com > article_dump.yml

clay import --yaml domain.com < article_dump.yml

```



If 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.



## Config



```bash

clay config --key  [value]

clay config --url  [value]

```



Show 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.



### Arguments



* `-k, --key` allows viewing or saving an api key

* `-u, --url` allows viewing or saving a url / site prefix

* `-r, --reporter` allows specifying how results should be logged (note: all reporters except `json` report `clay config` the same)



### Examples



```bash

# view all configuration options

clay config



# view 'local' api key

clay config --key local



# set 'local' api key

clay config --key local ab27s9d



# view 'qa' site prefix

clay config --url qa



# set 'qa' site prefix

clay config --url qa https://qa.domain.com:3001



# set a specific url

clay config --url my-cool-article domain.com/_components/article/instances/123

```



## Lint



```bash

clay lint [--concurrency ] [url]

```



Verify Clay data against standardized conventions and make sure all child components exist.



Linting 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`.



Instead 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).



### Arguments



* `-r, --reporter` allows specifying how results should be logged

* `-c, --concurrency` allows setting the concurrency of api calls



### Examples



```bash

# lint all components on a page

clay lint domain.com/_pages/123



# lint a page via public url

clay lint domain.com/2018/02/some-slug.html



# lint a component and its html

clay lint domain.com/_components/article/instances/abc.html



# lint a component specified via config alias

clay lint my-cool-article



# lint single schema

clay lint < components/article/schema.yml

```



## Import



```bash

clay import [--key ] [--concurrency ] [--publish] [--yaml] [site prefix]

```



Imports 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`.



The `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.



### Arguments



* `-k, --key` allows specifying an api key or alias

* `-r, --reporter` allows specifying how results should be logged

* `-c, --concurrency` allows setting the concurrency of api calls

* `-p, --publish` triggers publishing of imported pages

* `-y, --yaml` specifies that input is _bootstrap_ format



### Examples



```bash

# import a dispatch

clay import --key local localhost:3001 < db_dump.clay



# import and publish pages in a bootstrap

clay import --key qa --publish --yaml < bootstrap.yml



# pipe from 3rd party exporter

wordpress-export domain.com/blog | clay import --key local localhost.domain.com



# pipe from clay exporter

clay export --key prod domain.com/_components/article/instances/123 | clay import --key local localhost.domain.com



# import multiple dispatches

cat *.clay | clay import --key local localhost:3001



# import multiple bootstraps

tail -n +1 *.yml | clay import --key local --yaml localhost:3001



# recursively import multiple bootstraps

find . -name '*.yml' -exec cat "{}" \; | clay import --key local --yaml localhost:3001



# recursively import multiple bootstraps (bash v4+ & zsh)

cat **/*.yml | clay import --key local --yaml localhost:3001

```



## Export



```bash

clay export [--key ] [--concurrency ] [--size ] [--layout] [--yaml] [url]

```



Exports 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`.



If 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).



Instead 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.



```yaml

index: pages

size: 100

body:

  sort:

    updateTime:

        order: desc # sort by latest updated

  query:

    bool:

      must:

        -

          terms:

            siteSlug:

              - intelligencer # show only pages for a specific site

        -

          match:

            published: true # show only published pages



```



You 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`.



```yaml

index: published-products

size: 5

from: 10

sort:

  - price

body:

  query:

    match_all: {}

```



By 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.



### Arguments



* `-k, --key` allows specifying an api key or alias

* `-r, --reporter` allows specifying how results should be logged

* `-c, --concurrency` allows setting the concurrency of api calls

* `-s, --size` specifies the number of pages to export (defaults to 10)

* `-l, --layout` triggers exporting of layouts

* `-y, --yaml` specifies that output is _bootstrap_ format



### Examples



```bash

# export individual component

clay export domain.com/_components/article/instances/123 > article_dump.clay



# export individual page

clay export --yaml domain.com/_pages/123 > page_bootstrap.yml



# export page with layout

clay export --layout --yaml domain.com/_pages/123 > page_bootstrap.yml



# copy page to local environment

clay export domain.com/_pages/123 | clay import --key local local.domain.com



# export latest updated page

clay export --key prod --size 1 domain.com > recent_page.clay



# export custom query to dispatch

cat query.yml | clay export --key prod domain.com > db_dump.clay



# export custom query to bootstrap

clay export --yaml --key prod domain.com/sub-site < query.yml > pages.yml



# note that 'cat query.yml | clay export' and 'clay export < query.yml' are equivalent ways

# to pipe from a file into claycli in most operating systems



#

# other things you may export

#



# export single user

clay export domain.com/_users/abs8a7s8d --yaml > my_user.yml



# export all users

clay export domain.com/_users --yaml > users.yml



# export single list

clay export domain.com/_lists/tags > tags.clay



# export all lists

clay export domain.com/_lists > lists.clay



# export published page via public url

clay export domain.com/2017/02/some-slug.html



# export built-in 'New Page Templates' list (page uris will be unprefixed)

clay export domnain.com/_lists/new-pages

```



## Compile



```bash

clay compile [--watch] [--minify] [--inlined] [--linked] [--plugins ] [--globs ] [--reporter ]

```



Compile 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.



Specifying `--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.



A project specific clay config file is also supported, [read more here](https://github.com/clay/claycli#project-specific-config-file).



#### Arguments



* `-w, --watch` enables watching of source files after compilation

* `-m, --minify` enables minification and bundling of source files

* `-i, --inlined` enables the generation of base64 inlined font CSS

* `-l, --linked` enables the generation of linked font CSS

* `-p, --plugins` allows running additional postcss plugins when compiling styles

* `-g, --globs` allows compiling additional JavaScript to `public/js/_global.js`

* `-r, --reporter` allows specifying how results should be logged



#### Examples



```bash

# compile all assets once

clay compile



# compile and watch all assets

clay compile --watch



# compile all assets once for production environments

clay compile --minify



# compile all assets, creating both inlined and linked font CSS

clay compile --inlined --linked

```



### Media



```bash

clay compile media [--watch] [--reporter ]

```



Copy 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`).



* `components//media/` are referenced by component templates and get copied to `public/media/components//`

* `layouts//media/` are referenced by layout templates and get copied to `public/media/layouts//`

* `styleguides//media/` are referenced by that styleguide's CSS and get copied to `public/media/stylesguides//`

* `sites//media/` are favicons and other site-specific icons that are referenced by particular components in the `` of pages. They get copied to `public/media/sites//`



#### Arguments



* `-w, --watch` enables watching of source files after compilation

* `-r, --reporter` allows specifying how results should be logged



#### Examples



```bash

# compile media files once

clay compile media



# compile and watch media files

clay compile media --watch

```



### Fonts



```bash

clay compile fonts [--watch] [--minify] [--inlined] [--linked] [--reporter ]

```



Compile fonts from `styleguides//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..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..css` file with `@font-face` declarations that include a base64-encoded copy of the font.



`@font-face` declarations are generated based on the filename of the original font file, with a simple convention to support various weights and styles.



* `.` font with normal weight and style

* `-.` or `-.<ext>` specify a font weight _or_ style

* `<name>-<weight>-<style>.<ext>` specify a font weight _and_ style



All 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) `<name>` 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`.



Specifying `--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).



#### Arguments



* `-w, --watch` enables watching of source files after compilation

* `-m, --minify` enables minification of font CSS

* `-i, --inlined` enables the generation of base64 inlined font CSS

* `-l, --linked` enables the generation of linked font CSS

* `-r, --reporter` allows specifying how results should be logged



#### Examples



```bash

# compile linked fonts

clay compile fonts



# compile inlined fonts

clay compile fonts --inlined



# compile linked and inline fonts

clay compile fonts --inline --linked



# compile fonts once for production environments

clay compile fonts --minify

```



### Styles



```bash

clay compile styles [--watch] [--minify] [--plugins <space-separated list of postcss plugins>] [--reporter <reporter>]

```



Compile styleguide CSS files with PostCSS. Source files from `styleguides/<styleguide name>/components/<component name>.css` (and `styleguides/<styleguide name>/layouts/<layout name>.css`) will be compiled to `public/css/<component or layout name>.<styleguide name>.css`.



By 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.



Setting `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.



```scss

/* styleguides/example/components/example-component.css */

.some-twitter-icon {

  background-image: url('$asset-host/media/styleguides/example/twitter.svg');

  background-size: 22px 18px;

}

```



Specifying `--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).



#### Arguments



* `-w, --watch` enables watching of source files and their dependencies after compilation

* `-m, --minify` enables minification of CSS

* `-p, --plugins` allows running additional postcss plugins

* `-r, --reporter` allows specifying how results should be logged



#### Examples



```bash

# compile css

clay compile styles



# compile and watch css and any @import'ed css files

clay compile styles --watch



# compile css with additional postcss plugins

clay compile styles --plugins postcss-preset-env stylelint



# compile styles once for production environments

clay compile styles --minify

```



### Templates



```bash

clay compile templates [--watch] [--minify] [--reporter <reporter>]

```



Precompile 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.



* `public/js/_templates-a-d.js`

* `public/js/_templates-e-h.js`

* `public/js/_templates-i-l.js`

* `public/js/_templates-m-p.js`

* `public/js/_templates-q-t.js`

* `public/js/_templates-u-z.js`



Templates will also be compiled to `public/js/<name>.template.js`.



#### Arguments



* `-w, --watch` enables watching of source files after compilation

* `-m, --minify` enables bundling of precompiled templates

* `-r, --reporter` allows specifying how results should be logged



#### Examples



```bash

# precompile handlebars templates

clay compile templates



# precompile and bundle templates

clay compile templates --minify



# precompile, bundle, and watch templates

clay compile templates --minify --watch

```



### Scripts



```bash

clay compile scripts [--watch] [--minify] [--globs <space-separated glob strings>] [--reporter <reporter>]

```



Compile 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:



* `public/js/<name>.client.js` from compiled `client.js`

* `public/js/<name>.model.js` from compiled `model.js`

* `public/js/_models-<letter>-<letter>.js` from compiled and _bundled_ `model.js`

* `public/js/_kiln-plugins.js` from compiled kiln plugins in `services/kiln/`

* `public/css/_kiln-plugins.css` from compiled kiln plugin styles in their `.vue` components

* `public/js/_global.js` from compiled legacy scripts specified by the `--globs` argument

* `public/js/<number>.js` from compiled dependencies of `client.js`, `model.js`, kiln plugin, or global scripts

* `public/js/_deps-<letter>-<letter>.js` from compiled and bundled dependencies



This also creates a number of files that are used for instantiating component controllers, serving scripts, and speeding up incremental builds:



* `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)

* `public/js/_prelude.js` dynamic bundler initialization script

* `public/js/_postlude.js` dynamic bundler access script, adds `window.require()` which enables loading of bundled dependencies

* `public/js/_ids.json` cache of module IDs, used when serving bundles

* `public/js/_registry.json` cache of module dependencies, used when serving bundles

* `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)

* `browserify-cache.json` local cache for fast incremental builds, must be added to `.gitignore`



Specifying `--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).



This 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.



#### Dependency Management



Any files you `require()` or `import` in your `client.js`, `model.js`, kiln plugins, or legacy global JavaScript are compiled to `<number>.js` and `_deps-<letter>-<letter>.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.



```js

// in your resolve-media service

const getDependencies = require('claycli').compile.scripts.getDependencies;



/**

 * figure out what scripts and styles should be loaded on each page

 * @param  {object} media

 * @param  {array} media.scripts array of filenames from amphora

 * @param  {array} media.styles array of filenames from amphora

 * @param  {object} locals site info, edit mode info, etc from amphora

 */

function resolveMedia(media, locals) {

  const assetPath = locals.site.assetPath; // from site config



  // note: for this example, we're only dealing with scripts.

  // your own media resolution must also take into account styles, fonts, and templates

  if (locals.edit) {

    // edit mode, get script dependencies for linking (so, bundled / minified files)

    media.scripts = getDependencies(media.scripts, assetPath, { edit: true, minify: true });

  } else {

    // view mode, get script dependencies for inlining (so, individual dependency files)

    media.scripts = getDependencies(media.scripts, assetPath);

  }

}

```



By 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.



#### Kiln Plugins



This 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:



```js

// services/kiln/index.js

module.exports = () => {

  // add globals if they don't already exist

  window.kiln = window.kiln || {};

  window.kiln.validators = window.kiln.validators || {};

  window.kiln.inputs = window.kiln.inputs || {};

  window.kiln.plugins = window.kiln.plugins || {};

  // add your plugins into the globals

  window.kiln.validators['unique-url'] = require('./validate-unique-url');

  window.kiln.inputs['content-picker-button'] = require('./content-picker-button.vue');

  window.kiln.plugins['kiln-error-tracking'] = require('./kiln-tracking-plugin');

};

```



Any styles (denoted with `<style lang="postcss">` 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.



#### Legacy Global Scripts



If 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_.



#### Arguments



* `-w, --watch` enables watching of scripts and their dependencies after compilation

* `-m, --minify` enables minification of scripts

* `-g, --globs` allows compiling additional JavaScript

* `-r, --reporter` allows specifying how results should be logged



#### Examples



```bash

# compile scripts once

clay compile scripts



# compile and watch scripts and dependencies

clay compile scripts --watch



# compile scripts once for production environments

clay compile scripts --minify



# compile scripts, including legacy js

# note: this glob will match all '.js' files in 'global/js/' unless they end in '.test.js',

# which is a common unit testing convention

clay compile scripts --globs 'global/js/!(*.test).js'

```



### Project Specific Config File



Not 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:



* Adding PostCSS plugins to [`styles`](https://github.com/clay/claycli#styles) compilation

* Updating options passed into Autoprefixer

* Changing Babel browser target to meet your env support requirements



#### Arguments



The `claycli.config.js` file currently supports the following arguments:



* `plugins` (_Array_): list of PostCSS plugins that will be concatenated to the end of the list already supported by the `styles` compilation command

* `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

* `autoprefixerOptions` (_Object_): an Object which is [passed directly to `autoprefixer`](https://www.npmjs.com/package/autoprefixer#options) for style and Kiln plugin compilation

* `customTasks` (_Array_): an Array of Gulp tasks to execute with the `clay compile custom-tasks` command.

* `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']`.

#### Example



```js

'use strict';



module.exports = {

  plugins: [

    require('postcss-functions')({

      functions: {

        em: function (pixels, browserContext) {

          var browserContext = parseInt(browserContext, 10) || 16,

            pixels = parseFloat(pixels);



          return pixels / browserContext + 'em';

        }

      }

    })

  ],

  babelTargets:  { browsers: ['> 2%'] },

  autoprefixerOptions: { browsers: ['last 2 versions', 'ie >= 9', 'ios >= 7', 'android >= 4.4.2'] },

  customTasks: [{

    name: 'foobar',

    fn: (cb) => {

      // A gulp task to execute

      cb();

    }

  }]

};

```



### Custom Gulp Tasks



Because 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.



#### Example



For example, given the following `claycli.config.js` file:



```js

'use strict';



var { gulp } = require('claycli'),

  concat = require('gulp-concat'),

  uglify = require('gulp-uglify'),

  gutil = require('gulp-util'),

  argv = require('yargs').argv,

  gulpif = require('gulp-if');



module.exports = {

  customTasks: [

    {

      name: 'polyfill',

      fn: () => {

        return gulp.src([

          'global/polyfills.js',

          'global/modernizr.js'

        ])

        .pipe(concat('polyfills.js'))

        .pipe(gulpif(!argv.debug, uglify())).on('error', gutil.log)

        .pipe(gulp.dest('public/js'));

      }

    }

  ]

};

```

**Important Notes:**



1. Claycli exposes the instance of `gulp` that it users to make sure their is consistency between internal tasks and external ones

2. This example of a custom task is all done inline, but the objects can be organizes and managed in different files

3. When executing commands you have access to `argv` and can test options inside your custom functions.

4. 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.



Executing `clay compile custom-tasks` will execute this task to produce a `polyfills.js` file.



# Programmatic API



The 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.



```js

const { config, lint, import, export, compile } = require('claycli');

```



## Config



Get `key` or `url` from config



```js

config.get(type, alias);

```



Set `key` or `url` in config



```js

config.set(type, alias, value);

```



Get full configuration object



```js

config.getAll();

```



## Lint



Lint a url



```js

lint.lintUrl(url, { concurrency });

```



Lint a schema (passed in as a string of yaml)



```js

lint.lintSchema(yaml);

```



## Import



Import a string of dispatches or bootstraps to the specified (site prefix) url



```js

import(string, url, { key, concurrency, publish, yaml });

```



Parse a string of bootstrap data into a stream of prefixed dispatches. _Note: does NOT do http calls_



```js

import.parseBootstrap(string, url);

```



Parse 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_



```js

import.parseBootstrapObject(obj, url);

```



Parse a string of dispatches into a stream of prefixed dispatches. _Note: does NOT do http calls_



```js

import.parseDispatch(string, url);

```



## Export



Export a single url, e.g. `domain.com/_components/foo` or `domain.com/_pages`



```js

export.fromURL(url, { concurrency, layout, yaml });

```



Export the results of a query (passed in as a string of yaml)



```js

export.fromQuery(url, query, { key, concurrency, layout, yaml, size });

```



Clear the layouts cache. when exporting pages with layouts, they'll be cached so they don't need to be exported for every page



```js

export.clearLayouts();

```



## Compile



_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.



Compile media files



```js

compile.media({ watch });

```



Compile fonts



```js

compile.fonts({ minify, watch, inlined, linked });

```



Compile styles



```js

compile.styles({ minify, watch, plugins });

```



Compile templates



```js

compile.templates({ minify, watch });

```



Compile scripts



```js

compile.scripts({ minify, watch, globs });

```



Calculate script dependencies. _Note:_ when calling this from `resolveMedia`, the first argument is `media.scripts`



```js

compile.scripts.getDependencies(scripts, assetPath, { edit, minify });

```



# Contributing



Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/clay/claycli/issues/new).



This project is released under the [MIT license](https://github.com/clay/claycli/blob/master/LICENSE).