CLI Integration

The CLI is a standalone integration method for static sites. It automatically injects the cside script and prefixes your existing script URLs. 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 your-domain.com

Usage

Run the CLI after your build process to prefix all script URLs in your HTML files:

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

Replace domain

Replace your-domain.com with your actual domain configured in cside.

CLI Options

Usage: @cside.dev/cli <domain> [options]

Positionals:
  domain  The domain to process                                         [string]

Options:
      --version                        Show version number             [boolean]
  -d, --dir                            Directory containing HTML files to
                                       process. Defaults to .next and dist.
                                                                        [string]
  -f                                   Process a single file instead of a
                                       directory.                       [string]
  -s, --silent                         Disable output logging.
                                                      [boolean] [default: false]
      --enable-first-party-proxy       Enable first party proxy.
                                                      [boolean] [default: false]
      --enable-script-tracking         Enable script tracking.
                                                       [boolean] [default: true]
      --enable-security-headers-check  Enable security headers check.
                                                       [boolean] [default: true]
      --excluded-scripts               Scripts to exclude from prefixing.
                                                           [array] [default: []]
  -h, --help                           Show help                       [boolean]

Examples

Process a specific directory:

npx @cside.dev/cli your-domain.com --dir ./out

Process a single file:

npx @cside.dev/cli your-domain.com -f ./dist/index.html

Exclude specific scripts:

npx @cside.dev/cli your-domain.com --excluded-scripts "https://example.com/script.js"

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:

Injects the cside script into your HTML
Prefixes all third-party script URLs with the cside proxy
Adds the required referrerpolicy attributes

If your site uses a Content Security Policy, you still need to update it when using the CLI. Add proxy.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' proxy.csidetm.com; connect-src 'self' proxy.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 proxy.csidetm.com to allow the cside script and proxied scripts to execute
connect-src: If you use this directive, add proxy.csidetm.com to allow the cside script to communicate with the proxy server

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

Alternative integration methods

Manual script installation: For any site, add the script tag yourself
Next.js package: For Next.js apps with App Router or Pages Router