VibePresto CLI

CLI for managing WordPress pages, preparing static frontend builds, uploading versioned bundles, and creating multi-route VibePresto deployments.

Overview

The CLI supports two deployment styles:

• simple single-page uploads for raw HTML/CSS/JS bundles
• framework-aware build, verify, route inspection, and deployment for static/exported frontend apps

The CLI also validates VibePresto WordPress placeholders in uploaded HTML:

• data-vp-source="post"
• data-vp-field="post_title" and other supported WordPress-style fields
• placeholder diagnostics are surfaced in verify, upload, and deploy JSON output

Important behavior:

• data-vp-source="post" means the current queried WP_Post object used for the rendered request.
• In WordPress, both the post and page post types are represented by WP_Post.
• On a VibePresto page takeover, the current queried object is the page post type being viewed.
• On the configured Posts page, the current queried object is the page post type assigned in Reading Settings.
• On a single post view, the current queried object is the post post type being viewed.

Supported targets are static/exportable builds from common React, Next.js static export, Nuxt static export, Vite, Svelte/SvelteKit static output, TanStack static output, and similar projects that emit HTML plus assets on disk.

Use with npx

npx vibepresto --help

Project config

The CLI can optionally store project-local defaults in .vibepresto/config.json.

Create it explicitly:

npx vibepresto init --project-dir ./my-app --output-dir ./my-app/dist --site https://your-site.example --env local --json

Or let the CLI offer to create it the first time you run a config-aware command interactively.

Supported structure:

{
  "schemaVersion": 1,
  "project": {
    "name": "marketing-site",
    "framework": "react-vite",
    "projectDir": ".",
    "outputDir": "dist"
  },
  "defaults": {
    "bundleKind": "single-entry",
    "routeMode": "auto",
    "pageTitleStrategy": "from-route",
    "pagePrefix": "",
    "homepageRoute": "/"
  },
  "defaultEnvironment": "local",
  "environments": {
    "local": {
      "site": "http://localhost:8000",
      "uploadTarget": {
        "pageId": 123
      },
      "deployment": {
        "targets": [
          {
            "routePath": "/",
            "pageId": 123,
            "isHomepage": true
          },
          {
            "routePath": "/news",
            "pageId": 456
          }
        ]
      },
      "singlePostTemplate": {
        "lineageId": 12
      }
    }
  }
}

Notes:

• uploadTarget is for simple upload flows and can contain either pageId or postId.
• deployment.targets[] is for route-based deploy flows and is matched by routePath.
• singlePostTemplate.lineageId can be reused by posts set-default-template.
• Use --env <name> to select a non-default environment.
• CLI flags always override project config values.
• Route-based deploy mappings are currently page-backed. Use upload --post-id for direct single-post assignment.

Core commands

Auth

npx vibepresto login --site https://your-site.example
npx vibepresto whoami --site https://your-site.example --json
npx vibepresto logout --site https://your-site.example --revoke

Login notes:

• device authorization requests are rate-limited per IP to protect the public auth bootstrap endpoint
• if login is throttled, wait a few minutes and retry
• the CLI checks plugin compatibility metadata during login and authenticated commands
• if the plugin requires a newer CLI version, the CLI warns and suggests upgrade commands but still continues in v1

Framework prep

npx vibepresto detect --project-dir ./my-app --env local --json
npx vibepresto build --project-dir ./my-app --env local --json
npx vibepresto verify --output-dir ./my-app/dist --env local --json
npx vibepresto routes inspect --output-dir ./my-app/dist --env local --json

Force SPA fallback mode for router apps:

npx vibepresto routes inspect --output-dir ./dist --route-mode spa --json

Pages

npx vibepresto pages list --site https://your-site.example --json
npx vibepresto pages search --site https://your-site.example --query Home --json
npx vibepresto pages create --site https://your-site.example --title "Landing Page" --status draft --json
npx vibepresto pages set-status --site https://your-site.example --page-id 123 --status publish --json
npx vibepresto pages set-homepage --site https://your-site.example --page-id 123 --json
npx vibepresto pages set-posts-page --site https://your-site.example --page-id 456 --json

Posts

npx vibepresto posts list --site https://your-site.example --json
npx vibepresto posts search --site https://your-site.example --query Launch --json
npx vibepresto posts set-status --site https://your-site.example --post-id 789 --status publish --json
npx vibepresto posts set-default-template --site https://your-site.example --lineage-id 12 --json
npx vibepresto posts set-default-template --env local --json

Upload

Simple static folder upload:

npx vibepresto upload \
  --site https://your-site.example \
  --site-dir ./landing-page \
  --name "Landing page" \
  --page-id 123 \
  --json

Or reuse the environment uploadTarget from .vibepresto/config.json:

npx vibepresto upload --site-dir ./landing-page --env local --json

Assign directly to a single post:

npx vibepresto upload \
  --site https://your-site.example \
  --site-dir ./post-template \
  --post-id 789 \
  --json

Prebuilt artifact upload with route-aware metadata:

npx vibepresto upload \
  --site https://your-site.example \
  --zip ./dist.zip \
  --bundle-kind multi-entry \
  --route-manifest ./route-manifest.json \
  --json

Single-page folder mode rules:

• index.html must exist at the folder root
• local HTML/CSS/JS references must resolve inside that folder
• remote URLs, data: URLs, and anchors are allowed
• data-vp-* placeholders are allowed and validated without rewriting the HTML

Example placeholder markup:

<section>
  <h1 data-vp-source="post" data-vp-field="post_title">Fallback title</h1>
  <p data-vp-source="post" data-vp-field="author_display_name">Fallback author</p>
</section>

Deploy

Build, verify, inspect routes, upload, resolve pages, optionally create missing pages, and create a deployment:

npx vibepresto deploy \
  --site https://your-site.example \
  --project-dir ./my-app \
  --env local \
  --json

Deploy a prebuilt output directory in mixed mode:

npx vibepresto deploy \
  --site https://your-site.example \
  --output-dir ./dist \
  --env local \
  --create-missing-pages \
  --json

Preview the route and page mapping plan without uploading:

npx vibepresto deploy \
  --site https://your-site.example \
  --output-dir ./dist \
  --env local \
  --dry-run \
  --json

If .vibepresto/config.json defines deployment.targets[], deploy uses those route mappings as the authoritative target plan for that environment instead of resolving or creating pages automatically.

Useful deploy flags:

• --route-mode auto|manifest|spa
• --create-missing-pages
• --no-create-missing-pages
• --page-status draft|publish|pending|private
• --page-title-strategy from-manifest|from-route|explicit-prefix
• --page-prefix <slug-prefix>
• --homepage-route /

Bundle and deployment history

npx vibepresto bundles list --site https://your-site.example --json
npx vibepresto bundles versions --site https://your-site.example --bundle-id 12 --json
npx vibepresto bundles rollback --site https://your-site.example --page-id 123 --version 1 --json

npx vibepresto deployments list --site https://your-site.example --json
npx vibepresto deployments show --site https://your-site.example --deployment-id 3 --json
npx vibepresto deployments promote --site https://your-site.example --deployment-id 3 --bundle-version-id 18 --json
npx vibepresto deployments rollback --site https://your-site.example --deployment-id 3 --version 1 --json

JSON output

Success:

{
  "ok": true,
  "data": {}
}

Verification and upload/deploy responses may also include:

• placeholder_count
• placeholders
• warnings

Failure:

{
  "ok": false,
  "error": {
    "code": "bundle_verification_failed",
    "message": "Human-readable error message.",
    "details": {}
  }
}

Agent flow

Typical framework-aware flow:

npx vibepresto whoami --site https://your-site.example --json
npx vibepresto build --project-dir ./my-app --json
npx vibepresto routes inspect --output-dir ./my-app/dist --json
npx vibepresto deploy --site https://your-site.example --output-dir ./my-app/dist --create-missing-pages --json

The CLI is the main automation surface for Codex or other agents. Prefer --json so callers can branch on stable response data.