Skip to content

WP-CLI Publish Command

Use wp staatic publish to start a Staatic publication from WP-CLI. It is useful for cron, CI, deployment scripts, and hosts where browser-triggered publication tasks are unreliable.

The command still uses the Staatic settings configured in WordPress, including the selected deployment method, build settings, advanced settings, and Premium integrations.

The per-task Publication Task Timeout does not apply to WP-CLI; publication tasks run without a PHP time limit. The overall Publication Time Limit does apply: a publication that has been running longer than that limit, four hours by default, is canceled and marked as failed at the start of the next task. See Advanced Settings.

Syntax

wp staatic publish [--only-urls=<urls>] [--only-paths=<paths>] [--[no-]preview] [--[no-]deploy] [--[no-]force] [--[no-]verbose]

Staatic Premium with an active subscription adds the --merge and --partial options:

wp staatic publish [--only-urls=<urls>] [--only-paths=<paths>] [--[no-]merge] [--[no-]partial] [--[no-]preview] [--[no-]deploy] [--[no-]force] [--[no-]verbose]

A successful full publication prints task progress similar to this:

Setting up
Initializing crawler
Crawling WordPress site
Crawling...  100% [========================] 0:00 / 0:00
Finishing crawler
Post-processing
Initializing deployment
Deploying WordPress site
Deploying...  100% [=======================] 0:00 / 0:00
Finishing deployment
Finishing
Success: Publication finished in 11 seconds!

Sites using Premium Search can also show indexing tasks during publication.

Options

Option Default Description
--only-urls=<urls> none Publish a comma-separated list of URLs selectively, such as /, /contact/, or /sitemap.xml.
--only-paths=<paths> none Publish a comma-separated list of readable filesystem paths selectively.
--[no-]preview --no-preview Create a preview publication instead of a live publication, if the selected deployment method supports previews.
--[no-]deploy --deploy Deploy the publication after the build completes. Use --no-deploy to crawl and build without deploying or replacing the active publication.
--[no-]force --no-force Cancel the publication currently in progress before starting this one.
--[no-]verbose --no-verbose Include publication logs in the command output. Task names and progress bars are shown even without --verbose.

Premium-only options:

Option Default Description
--[no-]partial --no-partial Publish changes tracked since the active publication. This option is available with Staatic Premium and an active subscription.
--[no-]merge --merge with --partial, --only-urls or --only-paths, otherwise --no-merge Merge the new build into the currently active publication. Before 1.15.0, selective publications were not merged by default. This option is available with Staatic Premium and an active subscription.

--no-deploy crawls and builds the site but does not replace the active live or preview publication. Do not rely on --preview with Premium partial or merged publications; treat those modes as live-publication workflows.

Selective publications

Selective URLs must belong to the current WordPress site, and selective paths must be readable and map to URLs. Do not combine --partial with --only-urls or --only-paths.

Warning: without an active Staatic Premium subscription, or with --no-merge, a selective publication contains only the selected URLs and paths, and deploying it replaces your whole site. Amazon S3, GitHub and Local Directory remove every other file that is not retained, SFTP removes every other file from earlier Staatic deployments, and Netlify serves only the selected files.

Examples

Run a full live publication:

wp staatic publish

Run a preview publication with log output:

wp staatic publish --preview --verbose

Build the site without deploying it:

wp staatic publish --no-deploy

Publish a few specific URLs (see Selective publications first):

wp staatic publish --only-urls="/,/contact/,/sitemap.xml"

With Staatic Premium, publish a single URL and merge it into the active publication:

wp staatic publish --only-urls="/sitemap.xml"

Publish tracked changes using Staatic Premium:

wp staatic publish --partial

Cancel the current publication and start a new one:

wp staatic publish --force

Errors

When a publication fails, the command prints the error and exits with a non-zero status, so a cron job or CI pipeline can detect it. The publication is also marked as failed under Staatic > Publications.

Message What to do
Unable to publish; another publication is pending Wait for the running publication to finish, or add --force to cancel it and start yours.
The configured deployment method does not support preview publications. Remove --preview. Preview publications are only available on Staatic Cloud.
URL "…" is not part of this site. or URL "…" is malformed. Pass paths such as /contact/, or full URLs on the WordPress site.
Path "…" is not readable. or Path "…" is not convertible to a URL path. Pass a readable path inside the WordPress installation.
The --partial option cannot be used with --only-urls or --only-paths. Use either --partial or a selection, not both.
There is no active publication to merge the selection into. … Publish the whole site first, or add --no-merge.
Publication failed during … task with error …: The publication process took too long and was canceled. Raise the Publication Time Limit, or publish fewer URLs at a time.
Publication failed during … task with error … Run the command again with --verbose to see the publication log. If the task is a deployment task, check the deployment settings.
Publication was canceled The publication was canceled in the WordPress admin, or by another command with --force. Run it again.

Related pages