https://github.com/swup/cli
Create swup plugins and themes in seconds, or validate your website 🚤
https://github.com/swup/cli
cli page-transitions plugins swup themes
Last synced: 9 months ago
JSON representation
Create swup plugins and themes in seconds, or validate your website 🚤
- Host: GitHub
- URL: https://github.com/swup/cli
- Owner: swup
- License: mit
- Created: 2019-05-12T21:09:47.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2025-08-06T18:07:57.000Z (11 months ago)
- Last Synced: 2025-08-06T20:18:36.741Z (11 months ago)
- Topics: cli, page-transitions, plugins, swup, themes
- Language: TypeScript
- Homepage: https://swup.js.org/cli
- Size: 1.56 MB
- Stars: 5
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Swup CLI
[](https://npmjs.org/package/@swup/cli)
[](https://github.com/gmrchk/cli/blob/main/package.json)
[](https://oclif.io)
A command-line interface (CLI) to help develop [swup](https://swup.js.org/) 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](#installation)
- [Usage](#usage)
- [Commands](#commands)
## Installation
Install the CLI globally from npm.
```sh
npm install -g @swup/cli
```
## Usage
The CLI will install a binary called `swup` you can run, followed by any of the provided [commands](#commands).
```sh
$ swup [command]
> Running command...
$ swup --help [command]
> Show help for command [command]
$ swup --version
> @swup/cli/5.0.3 darwin-arm64 node-v18.16.0
```
## Commands
* [`swup create NAME`](#swup-create-name)
* [`swup help [COMMANDS]`](#swup-help-commands)
* [`swup package:build`](#swup-packagebuild)
* [`swup package:check`](#swup-packagecheck)
* [`swup package:dev`](#swup-packagedev)
* [`swup package:format`](#swup-packageformat)
* [`swup package:lint`](#swup-packagelint)
* [`swup validate`](#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= [default: plugin] Type
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](https://github.com/swup/cli/blob/5.0.3/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](https://github.com/oclif/plugin-help/blob/v5.2.20/src/commands/help.ts)_
## `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](https://github.com/swup/cli/blob/5.0.3/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](https://github.com/swup/cli/blob/5.0.3/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](https://github.com/swup/cli/blob/5.0.3/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](https://github.com/swup/cli/blob/5.0.3/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](https://github.com/swup/cli/blob/5.0.3/src/commands/package/lint.ts)_
## `swup validate`
Validate a swup-powered site
```
USAGE
$ swup validate [-u | -s ] [-c] [-l ] [-t
all|containers|transition-duration|transition-styles] [-p] [--containers ] [--animation ] [--styles
]
FLAGS
-c, --crawl Crawl site
-l, --limit= Limit
-p, --parallel Parallel
-s, --sitemap= Sitemap
-t, --tests= [default: all] Tests
-u, --url= URL
--animation= [default: [class*="transition-"]] Animation selector
--containers= [default: #swup] Containers
--styles= [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= 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= 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= URL
Base URL to validate. Will validate this single URL only, unless --crawl is specified.
--animation= Animation selector
Selector of elements that should be animated.
--containers= Containers
Selectors of containers to validate, separated by comma.
--styles= Expected styles
CSS properties expected to change during animations, separated by comma.
```
_See code: [src/commands/validate.ts](https://github.com/swup/cli/blob/5.0.3/src/commands/validate.ts)_