# DXP Directus CLI

[![NPM version](https://img.shields.io/npm/v/@archer-edu/dxp-directus-cli.svg?style=flat)](https://www.npmjs.com/package/@archer-edu/dxp-directus-cli) [![NPM monthly downloads](https://img.shields.io/npm/dm/@archer-edu/dxp-directus-cli.svg?style=flat)](https://npmjs.org/package/@archer-edu/dxp-directus-cli) [![NPM total downloads](https://img.shields.io/npm/dt/@archer-edu/dxp-directus-cli.svg?style=flat)](https://npmjs.org/package/@archer-edu/dxp-directus-cli)

This is the DXP Directus CLI for incorporating CMS data from Directus into our into DXP website builds.

## Getting started

Install the CLI

``` 
yarn add @archer-edu/dxp-directus-cli -D
```

Once it is installed, you can call `pull-blog`, `pull-data`, `pull-pages`, `push-page`, `promote-version`, `lighthouse-run`, or `ghost-inspector-run`.

## Pull Blog

Usage:

    cmsctl pull-blog|b [options] <siteId>

Pull a site's blog posts to the 'blog' directory inside content

Options:

```
  -b, --blog-dir              Change the 'blog' path. (This directory is relative to /content)
  -i, --download-images <d>   Download images to a directory (ie 'assets/images'). If omitted, images use the CDN
  -r, --redirect [redirect]   Add a global redirect for each of the blog entries, relative to their path (slug/redirect).
  -t, --tag                   Pull content versions of this name
  -d, --debug                 Enable debug mode
  -h, --help                  Display help for command
```


## Pull data
Usage: 

    cmsctl pull-data|d [options] <siteId>

Pull site data from directus and write to the 'data' directory

Options:

```
  -D, --directory <directory>  Directory output for file creation.
  -f, --force                  Force-delete the directory before writing files.
  -d, --debug                  Enable debug mode
  -t, --tag                    Pull content versions of this name
  -r, --drafts                 Include drafts (used for preview environment)
  -h, --help                   Display help for command
```

## Pull Pages

Usage:

    cmsctl pull-pages|p [options] <siteId>

Pull content pages from directus into the 'content' directory

Options:

```
  -d, --debug  Enable debug mode
  -t, --tag Pull content versions of this name
  -i, --download-images  <imageDir> Download images to a directory (ie 'assets/images'). If omitted, images use the CDN
  -h, --help   display help for command
```

## Push Page

Usage:

    cmsctl push-page [options] <path-to-md-file>

Create one brand-new Directus page from a local Markdown file.

Options:

```
  -s, --site-id <siteId>  Directus site key override. Defaults to package.json siteId.
  -T, --token <token>    Directus API token (falls back to DIRECTUS_TOKEN)
  -i, --download-images <imageDir> Download images to a directory relative to the src folders (ie 'assets/images'). If omitted, images use the CDN
  -d, --debug            Enable debug mode
  --dry-run              Validate and print the planned create without mutating Directus
  -h, --help             Display help for command
```

Add the Directus site ID to the dependent repo's `package.json`:

```json
{
  "scripts": {
    "push:page": "cmsctl push-page"
  },
  "siteId": "70768adb-e3f9-4a3f-a8d6-7154628a1e1a"
}
```

Example:

```bash
DIRECTUS_TOKEN=... cmsctl push-page src/content/example-page.md --dry-run
DIRECTUS_TOKEN=... cmsctl push-page src/content/example-page.md
DIRECTUS_TOKEN=... cmsctl push-page src/content/example-page.md -i assets/images
```

Safety constraints:

- creates one page per command
- only supports brand-new pages
- rejects existing page, section, or item IDs in local front matter
- rejects remote slug collisions before creating Directus records
- does not update, delete, create parent pages, or upload assets
- rewrites the local Markdown file from Directus after a successful create

## Promote Version

Usage:

    cmsctl promote-version [options] <siteId> <tag>

Promote a site's versioned blogs and pages to become the main content for the provided version tag.

Options:

```
  -d, --debug  Enable debug mode
  -T, --token <token>  Directus API token (falls back to DIRECTUS_TOKEN env var)
```

## Ghost Inspector Run

Usage:

    cmsctl ghost-inspector-run|gir [options] [startUrl]

Runs the Ghost Inspector suite configured in `package.json` and waits for the suite result to complete.

Options:

```
  --api-key <apiKey>              Ghost Inspector API key (falls back to DIRECTUS_CLI_GHOST_API_KEY)
  --suite-id <suiteId>            Ghost Inspector suite ID. Overrides package.json configuration.
  --start-url <startUrl>          Alternate start URL to use for this suite execution.
  --poll-interval <pollInterval>  Polling interval in seconds
  --max-attempts <maxAttempts>    Maximum number of polling attempts
  --ignore-failures               Exit successfully even when the Ghost Inspector suite fails
```

Add the suite ID to the dependent repo's `package.json`:

```json
{
  "scripts": {
    "test:ghost-inspector": "cmsctl gir"
  },
  "siteId": "70768adb-e3f9-4a3f-a8d6-7154628a1e1a",
  "ghostInspectorSuiteId": "ghost-inspector-suite-id"
}
```

CI can pass an ephemeral or basic-authenticated URL through the script:

```bash
yarn web test:ghost-inspector "$AUTHED_BASE_URL"
```

The command also supports `"ghostInspector": { "suiteId": "ghost-inspector-suite-id" }` if you prefer a namespaced package field.

`--ignore-failures` can also be set with `DIRECTUS_CLI_GHOST_INSPECTOR_IGNORE_FAILURES=true`.