Home / Documentation / Administrator Guide / WP-CLI / Publish Command

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.

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 --no-merge, unless --partial is used Merge the new build with the currently active publication. --partial implies merge behavior. This option is available with Staatic Premium and an active subscription.

Selective URLs must belong to the current WordPress site. Selective paths must be readable and mappable to URLs. Do not combine --partial with --only-urls or --only-paths; use --merge for Premium merged selective publications.

--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.

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:

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

Publish and merge a selected URL with the active publication using Staatic Premium:

wp staatic publish --merge --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

Failure cases

Common failure cases:

  • another publication is in progress and --force is not used;
  • a selective URL or path fails validation;
  • --partial is combined with --only-urls or --only-paths;
  • no crawl URLs can be enqueued;
  • the selected deployment method is missing or fails validation;
  • a publication task fails or the publication is canceled while running.

Failed publications are marked as failed in Staatic. Review the command output and Staatic logs to identify the failed task.

Related pages