Skip to main content
Supported frameworks
Language

CLI Integration

Use the cside CLI tool to automatically add cside to static HTML files after your build process.

The CLI is a standalone integration method for static sites. It automatically injects the cside monitoring script into your HTML files. No manual script tag needed.

No need to add the script manually

When using the CLI, there is no need to add the cside script to your site. The CLI adds it for you automatically. Use either the CLI or manual script installation, not both.

Static HTML only

The CLI only supports static HTML files. For SSR applications, use the manual script or Next.js package instead.

Supported frameworks

The CLI works with any framework that outputs static HTML files:

  • Astro (static mode)
  • Next.js (static export)
  • Gatsby
  • Nuxt (static mode)
  • SvelteKit (static adapter)
  • Eleventy (11ty)
  • Hugo
  • VitePress / VuePress
  • Docusaurus

Any other framework that outputs static HTML files will also work. The CLI automatically detects .next and dist output folders, or specify a custom directory with --dir.

Installation

npm i @cside.dev/cli

Or run directly without installing:

npx @cside.dev/cli

Usage

Run the CLI after your build process to inject the cside script into your HTML files:

// package.json
{
  "scripts": {
    "build": "next build && npx @cside.dev/cli"
  }
}

CLI Options

Usage: @cside.dev/cli [options]

Options:
      --version  Show version number                                   [boolean]
  -d, -f, --dir  Directory which include html files to process. By default we'll
                 try to look for a `.next` and `dist` folder. Also a single file
                 can be used.                                           [string]
  -s, --silent   Disable outputting processed html files.
                                                      [boolean] [default: false]
  -t, --team, --team-id
                 Inject a team-scoped cside script host using the provided team
                 ID.                                                     [string]
      --fingerprint
                 Inject cside fingerprint hosts on csidefd.com instead of the
                 default csidetm.com domain.
                                                      [boolean] [default: false]
  -h, --help     Show help                                             [boolean]

Examples

Process a specific directory:

npx @cside.dev/cli --dir ./out

Process a single file:

npx @cside.dev/cli --dir ./dist/index.html

Inject a team-scoped script host:

npx @cside.dev/cli --team-id 345678765434567890

When to use the CLI

Use the CLI if:

  • You have a static site (SSG) build process
  • You want a zero-code integration
  • You don’t want to modify your source code

The CLI automatically:

  1. Injects the cside script into your HTML
  2. Adds the required referrerpolicy attributes

Content Security Policy (CSP)

If your site uses a Content Security Policy, you still need to update it when using the CLI. Add *.csidetm.com to your script-src and connect-src directives. This is only required if you use those directives. If connect-src is not present, you do not need to add connect-src:

Content-Security-Policy: script-src 'self' *.csidetm.com; connect-src 'self' *.csidetm.com
Only if you use these directives

You only need to update your CSP if you already have script-src or connect-src directives defined. If you don’t use CSP, or don’t use these specific directives, no changes are needed.

What each directive allows:

  • script-src: If you use this directive, add *.csidetm.com to allow the cside script to execute
  • connect-src: If you use this directive, add *.csidetm.com to allow the cside script to communicate with the edge infrastructure

For more details on CSP configuration, see Adding cside to your CSP and CSP Reporting Configuration.

Alternative integration methods

Was this page helpful?