### Install and Check CLI Version

Source: https://context7.com/apostrophecms/cli/llms.txt

Install the CLI globally using npm. Check the CLI version and the installed Apostrophe core version within a project.

```bash
# Install globally
npm install -g @apostrophecms/cli

# Check the CLI version (also reports installed Apostrophe version when inside a project)
apos --version
# Apostrophe CLI: v3.5.0
# Apostrophe v3.9.0 is installed in this project.

# Print help (shown automatically when no arguments are provided)
apos --help
# Usage: apostrophe [options] [command]
# Commands:
#   create <shortname-without-spaces>
#   add <module-type> <module-name>
```

--------------------------------

### Generated Widget View Template

Source: https://context7.com/apostrophecms/cli/llms.txt

Example of a generated Nunjucks template for a widget. This file defines the HTML structure for the widget.

```html
<!-- Generated modules/image-gallery-widget/views/widget.html -->
<section data-image-gallery-widget>
</section>
```

--------------------------------

### Registering Widget Module and Using in an Area

Source: https://context7.com/apostrophecms/cli/llms.txt

Configuration for `app.js` to register a widget module and an example of how to use the widget within a page template or another module's fields via an 'area'.

```js
// Register the widget in app.js and add it to an area:
require('apostrophe')({
  shortName: 'my-website',
  modules: {
    'image-gallery-widget': {}
  }
});

// Use inside a page template or another module's fields:
// module.exports = {
//   fields: {
//     add: {
//       main: {
//         type: 'area',
//         options: {
//           widgets: {
//             'image-gallery': {}
//           }
//         }
//       }
//     }
//   }
// };
```

--------------------------------

### Generated Module Code (CommonJS vs ESM)

Source: https://context7.com/apostrophecms/cli/llms.txt

Example of generated module code for both CommonJS and ESM projects. The syntax differs based on the project's `package.json` type declaration.

```javascript
// Generated modules/analytics-tracking/index.js (CommonJS project)
module.exports = {
  extend: '@apostrophecms/module',
  init(self) {

  }
};

// Generated modules/analytics-tracking/index.js (ESM project, "type": "module")
export default {
  extend: '@apostrophecms/module',
  init(self) {

  }
};
```

--------------------------------

### Create a New ApostropheCMS Project

Source: https://context7.com/apostrophecms/cli/llms.txt

Scaffold a new ApostropheCMS project using a starter kit. Supports default, named, custom GitHub repositories, full Git URLs, and remote MongoDB connections. Automatically handles hybrid Astro + Apostrophe projects.

```bash
# Create a project using the default starter kit (apostrophecms/public-demo)
apos create my-website
# ✔ Clones https://github.com/apostrophecms/public-demo.git → my-website/
# ✔ Replaces shortName tokens in app.js and package.json
# ✔ Generates session secret and disabledFileKey
# ✔ Runs npm install (with spinner)
# ✔ Prompts for admin password then runs: node app.js @apostrophecms/user:add admin admin

# Use an official Apostrophe starter kit by short name
apos create my-shop --starter ecommerce
# Clones https://github.com/apostrophecms/starter-kit-ecommerce.git

# Use a specific GitHub repository (owner/repo shorthand)
apos create my-site --starter myorg/my-custom-starter

# Use a full Git URL
apos create my-site --starter https://github.com/myorg/my-starter.git

# Create a project connected to a hosted MongoDB instance
apos create my-site --mongodb-uri "mongodb+srv://user:pass@cluster.mongodb.net/mydb"
# Sets APOS_MONGODB_URI env var when creating the admin user

# Hybrid Astro + ApostropheCMS project (auto-detected via presence of backend/ dir)
apos create my-astro-site --starter apostrophecms/astro-public-demo
# ✔ Runs: npm install --prefix backend
# ✔ Runs: npm install --prefix frontend
```

--------------------------------

### Generate a Piece-Type Module with `apos add piece`

Source: https://context7.com/apostrophecms/cli/llms.txt

Use this command to create a new piece-type module. Add the `--page` flag to also generate a corresponding piece-page module for index/detail rendering.

```bash
# Add a basic piece type
apos add piece article

# Creates: modules/article/index.js

# Add a piece type with an accompanying piece-page type
apos add piece article --page

# Creates:
#   modules/article/index.js
#   modules/article-page/index.js
#   modules/article-page/views/index.html
#   modules/article-page/views/show.html
```

--------------------------------

### Generate a Widget-Type Module with `apos add widget`

Source: https://context7.com/apostrophecms/cli/llms.txt

Scaffolds a new widget-type module. Use the `--player` flag to additionally generate a browser-side JavaScript player file for interactive widgets.

```bash
# Add a basic widget type
apos add widget image-gallery

# Creates:
#   modules/image-gallery-widget/index.js
#   modules/image-gallery-widget/views/widget.html

# Add a widget with a browser-side player
apos add widget image-gallery --player

# Creates additionally:
#   modules/image-gallery-widget/ui/src/index.js
```

--------------------------------

### Uninstall Cleanup Script

Source: https://context7.com/apostrophecms/cli/llms.txt

This bash script is executed by npm's `preuninstall` hook to clear the CLI's in-memory configuration and remove its configuration file from the disk, ensuring no user data remains after uninstallation.

```bash

```

--------------------------------

### Persistent CLI Configuration Management

Source: https://context7.com/apostrophecms/cli/llms.txt

Manage user-specific CLI configuration, including initialization, reading/writing values, and clearing the configuration. This ensures persistent settings across CLI invocations.

```javascript
const confUtils = require('@apostrophecms/cli/lib/conf-utils');

// Initialise config on first run (sets uid if missing, prints welcome message)
const details = await confUtils.checkConf();
// → { uid: 'e3b0c442-98fc-1c14-b39f-...' }

// Read a config value
const lastNotified = confUtils.getConf('versionNotified');
// → '3.4.0' (or undefined if never set)

// Write a config value
confUtils.setConf('versionNotified', '3.5.0');

// Get the path to the config file on disk
const filePath = confUtils.getPath();
// → '/Users/alice/.config/@apostrophecms/cli/cli_config.json'

// Clear all config values (used during npm uninstall via preuninstall script)
confUtils.clearConf();
```

--------------------------------

### Styled Terminal Output and Utility Functions

Source: https://context7.com/apostrophecms/cli/llms.txt

Use these functions for styled logging, dependency checks, project path resolution, ESM detection, version parsing, file content replacement, secret generation, and running shell commands with spinners.

```javascript
const util = require('@apostrophecms/cli/lib/util');

// Styled log output
util.log('create', 'Starting project setup...');
// [Apostrophe] [create] Starting project setup...

// Styled success (also checks npm for CLI updates)
await util.success('add module');

// Styled error with message (also checks npm for CLI updates)
await util.error('add piece', 'Unable to find app.js in the current directory.');

// Find the nearest project root (walks up the tree looking for app.js)
const appPath = await util.getAppPath('my-command');
// Returns './' or '../' etc., or null if not found

// Detect ESM project
const isEsm = await util.isEsm('my-command');
// Returns true if package.json has "type": "module"

// Convert CJS boilerplate to ESM syntax
const code = util.esmify('module.exports = { extend: "@apostrophecms/module" }', true);
// → 'export default { extend: "@apostrophecms/module" }'

// Get Apostrophe major version string
const major = await util.getMajorVersion('create', '3.9.1');
// → '3'

// Generate a random 16-char hex secret
const secret = util.secret();
// → 'a3f9c21b7e084d56'

// Replace tokens in files
util.replaceInFiles(['app.js', 'package.json'], /(shortName:).*?,/gi, "$1 'my-project',");

// Run a shell command with an ora spinner
await util.spawnWithSpinner('npm install', {
  spinnerMessage: 'Installing packages. This will take a little while...', 
  codeMessage: 'Spawn process error code:'
});
```

--------------------------------

### Programmatically Clear CLI Configuration

Source: https://context7.com/apostrophecms/cli/llms.txt

This JavaScript code demonstrates how to programmatically clear the CLI configuration. It uses `confUtils.clearConf()` and `fs.unlinkSync()` to remove the configuration file.

```javascript
// Equivalent programmatic usage:
const confUtils = require('@apostrophecms/cli/lib/conf-utils');
const fs = require('fs');

confUtils.clearConf();
const filePath = confUtils.getPath();
try {
  fs.unlinkSync(filePath);
  console.log('CLI config removed.');
} catch (err) {
  console.error('Could not remove config file:', filePath, err.message);
}
```

--------------------------------

### Reset CLI Configuration

Source: https://context7.com/apostrophecms/cli/llms.txt

Run this script to delete the CLI configuration file. This is useful for resetting the CLI state.

```bash
node node_modules/@apostrophecms/cli/scripts/remove-conf.js
```

--------------------------------

### Generate a Generic Module

Source: https://context7.com/apostrophecms/cli/llms.txt

Scaffold a new generic Apostrophe module. This command must be run from within an Apostrophe project root. It automatically uses ESM syntax if the project is configured for it.

```bash
apos add module analytics-tracking

# Creates: modules/analytics-tracking/index.js
```

--------------------------------

### Register Module in app.js

Source: https://context7.com/apostrophecms/cli/llms.txt

After generating a module, it needs to be registered in the project's `app.js` file to be active.

```javascript
// After generation, register the module in app.js:
require('apostrophe')({
  shortName: 'my-website',
  modules: {
    'analytics-tracking': {}
  }
});
```

--------------------------------

### Registering Piece and Piece-Page Modules in `app.js`

Source: https://context7.com/apostrophecms/cli/llms.txt

Configuration for `app.js` to register newly generated piece and piece-page modules. Ensure the piece-page type is also added to the `@apostrophecms/page` module's `types` array.

```js
// Register both modules in app.js:
require('apostrophe')({
  shortName: 'my-website',
  modules: {
    'article': {},
    'article-page': {}
  }
});

// Also add the page type to @apostrophecms/page's "types" array:
// modules/@apostrophecms/page/index.js
module.exports = {
  options: {
    types: [
      { name: 'article-page', label: 'Article Index' }
    ]
  }
};
```

--------------------------------

### Generated Widget-Type Module Code

Source: https://context7.com/apostrophecms/cli/llms.txt

Boilerplate code for the generated `index.js` file for a widget-type module. Customize the `label` and `fields` as required.

```js
// Generated modules/image-gallery-widget/index.js
module.exports = {
  extend: '@apostrophecms/widget-type',
  options: {
    label: 'Image Gallery Widget',
  },
  fields: {
    add: {}
  }
};
```

--------------------------------

### Generated Piece-Type and Piece-Page Module Code

Source: https://context7.com/apostrophecms/cli/llms.txt

Boilerplate code for generated `index.js` files for piece-type and piece-page modules. Customize `label`, `pluralLabel`, and `fields` as needed.

```js
// Generated modules/article/index.js
module.exports = {
  extend: '@apostrophecms/piece-type',
  options: {
    label: 'Article',
    // Additionally add a `pluralLabel` option if needed.
  },
  fields: {
    add: {},
    group: {}
  }
};

// Generated modules/article-page/index.js (when --page is used)
module.exports = {
  extend: '@apostrophecms/piece-page-type',
  options: {
    label: 'Article Page',
    pluralLabel: 'Article Pages',
  },
  fields: {
    add: {},
    group: {}
  }
};
```

--------------------------------

### Code Template Generation for Modules, Pieces, and Widgets

Source: https://context7.com/apostrophecms/cli/llms.txt

Generate boilerplate code strings for various ApostropheCMS components like modules, piece types, and widgets. Supports both CommonJS and ESM output formats.

```javascript
const boilerplate = require('@apostrophecms/cli/lib/boilerplate');

// Generate all templates for a given module name
const templates = boilerplate('blog-post', {});

// Access the generic module config
console.log(templates.current['add-module'].moduleConfig);
// module.exports = {
//   extend: '@apostrophecms/module',
//   init(self) {
//
//   }
// };

// Access the piece type config (label is auto-Title-Cased from the name)
console.log(templates.current['add-piece'].pieceConfig);
// module.exports = {
//   extend: '@apostrophecms/piece-type',
//   options: {
//     label: 'Blog Post',
//   },
//   fields: { add: {}, group: {} }
// };

// Access the widget config
console.log(templates.current['add-widget'].widgetsConfig);
// module.exports = {
//   extend: '@apostrophecms/widget-type',
//   options: { label: 'Blog Post Widget' },
//   fields: { add: {} }
// };

// Access the widget Nunjucks view
console.log(templates.current['add-widget'].widgetsView);
// <section data-blog-post-widget>
// </section>

// Access the browser-side player stub
console.log(templates.current['add-widget'].jsConfig);
// export default () => {
//   apos.util.widgetPlayers['blog-post'] = {
//     selector: '[data-blog-post-widget]',
//     player: function(el) { /* Add player code */ }
//   };
// };
```

--------------------------------

### Generated Widget Player Code

Source: https://context7.com/apostrophecms/cli/llms.txt

Browser-side JavaScript for a widget player, registered using `apos.util.widgetPlayers`. This code runs in the browser to enhance widget functionality.

```js
// Generated modules/image-gallery-widget/ui/src/index.js (when --player is used)
export default () => {
  apos.util.widgetPlayers['image-gallery'] = {
    selector: '[data-image-gallery-widget]',
    player: function(el) {
      // Add player code
    }
  };
};
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.