Swup CLI

A command-line interface (CLI) to help develop swup sites and plugins.

• Validate your website in CI/CD
• Create plugins and themes from a best-practice template
• Bundle plugins and themes using microbundle

Contents

• Installation
• Usage
• Commands

Installation

Install the CLI globally from npm.

npm install -g @swup/cli

Usage

The CLI will install a binary called swup you can run, followed by any of the provided commands.

$ swup [command]
> Running command...
$ swup --help [command]
> Show helpforcommand [command]
$ swup --version
> @swup/cli/5.0.3 darwin-arm64 node-v18.16.0

Commands

• swup create NAME
• swup help [COMMANDS]
• swup package:build
• swup package:check
• swup package:dev
• swup package:format
• swup package:lint
• swup validate

swup create NAME

Create a swup plugin or theme

USAGE
$ swup create NAME [-t plugin|theme]
ARGUMENTS
NAME Name of the plugin to create
FLAGS
-t, --type=<option> [default: plugin] Type
<options: plugin|theme>
DESCRIPTION
Create a swup plugin or theme
Generate a new swup plugin or theme from an official, best-practice template
EXAMPLES
$ swup create SwupExamplePlugin
$ swup create SwupExampleTheme
FLAG DESCRIPTIONS
-t, --type=plugin|theme Type
Choose the type of project to create: plugin or theme. Not required if name ends with "Plugin" or "Theme".

See code: src/commands/create.ts

swup help [COMMANDS]

Display help for swup.

USAGE
$ swup help [COMMANDS] [-n]
ARGUMENTS
COMMANDS Command to show help for.
FLAGS
-n, --nested-commands Include all nested commands in the output.
DESCRIPTION
Display help for swup.

See code: @oclif/plugin-help

swup package:build

Build package

USAGE
$ swup package:build [--check]
FLAGS
--[no-]check Check package info
DESCRIPTION
Build package
Build package code for distribution using microbundle
EXAMPLES
$ swup package:build
FLAG DESCRIPTIONS
--[no-]check Check package info
Check for required package.json fields before bundling. Disable using --no-check.

See code: src/commands/package/build.ts

swup package:check

Check package info

USAGE
$ swup package:check
DESCRIPTION
Check package info
Ensure a bundle package.json is valid
EXAMPLES
$ swup package:check

See code: src/commands/package/check.ts

swup package:dev

Develop package

USAGE
$ swup package:dev [--check]
FLAGS
--[no-]check Check package info
DESCRIPTION
Develop package
Build package code for development using microbundle and watch for changes
EXAMPLES
$ swup package:dev
FLAG DESCRIPTIONS
--[no-]check Check package info
Check for required package.json fields before bundling. Disable using --no-check.

See code: src/commands/package/dev.ts

swup package:format

Format package

USAGE
$ swup package:format
DESCRIPTION
Format package
Fix code formatting issues using prettier
EXAMPLES
$ swup package:format

See code: src/commands/package/format.ts

swup package:lint

Lint package

USAGE
$ swup package:lint
DESCRIPTION
Lint package
Check code for formatting issues using prettier
EXAMPLES
$ swup package:lint

See code: src/commands/package/lint.ts

swup validate

Validate a swup-powered site

USAGE
$ swup validate [-u <value> | -s <value>] [-c] [-l <value>] [-t
all|containers|transition-duration|transition-styles] [-p] [--containers <value>] [--animation <value>] [--styles
<value>]
FLAGS
-c, --crawl Crawl site
-l, --limit=<value> Limit
-p, --parallel Parallel
-s, --sitemap=<value> Sitemap
-t, --tests=<option> [default: all] Tests
<options: all|containers|transition-duration|transition-styles>
-u, --url=<value> URL
--animation=<value> [default: [class*="transition-"]] Animation selector
--containers=<value> [default: #swup] Containers
--styles=<value> [default: opacity,transform] Expected styles
DESCRIPTION
Validate a swup-powered site
Crawl your site and validate that all pages are accessible and render correctly
EXAMPLES
$ swup validate
$ swup validate --url https://mysite.com/about
$ swup validate --crawl --url https://mysite.com
$ swup validate --tests containers,transition-duration
$ swup validate --asynchronous
FLAG DESCRIPTIONS
-c, --crawl Crawl site
Crawl the site for all public URLs and validate all found pages. Requires the --url flag as a base URL.
-l, --limit=<value> Limit
Limit the number of pages to validate when crawling or reading from a sitemap.
-p, --parallel Parallel
Run all tests asynchronously. A lot faster, but might cause issues.
-s, --sitemap=<value> Sitemap
If no URL is passed, the local sitemap file will be scanned for public URLs. Accepts a local filepath or URL.
-t, --tests=all|containers|transition-duration|transition-styles Tests
Specify which tests to run when validating. Defaults to all.
-u, --url=<value> URL
Base URL to validate. Will validate this single URL only, unless --crawl is specified.
--animation=<value> Animation selector
Selector of elements that should be animated.
--containers=<value> Containers
Selectors of containers to validate, separated by comma.
--styles=<value> Expected styles
CSS properties expected to change during animations, separated by comma.

See code: src/commands/validate.ts