VibePresto CLI

CLI for uploading trusted single-page static bundles to the VibePresto WordPress plugin.

Default Workflow

VibePresto's MVP model is:

one WordPress page = one bundle lineage = one active assignment.

Initialize a project once:

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

That writes .vibepresto/config.json. After that, commands use the configured environment site and upload target automatically:

npx vibepresto login
npx vibepresto whoami --json
npx vibepresto build --json
npx vibepresto verify --json
npx vibepresto upload --site-dir ./my-app/dist --json

Use --site <url> only to override config, and use --env <name> to select another environment. If no config site exists, the CLI can reuse the only saved auth site when exactly one exists.

Inspect what the CLI resolved:

npx vibepresto config show --json

Project Files

• .vibepresto/config.json stores project defaults, environments, site URLs, output directories, and optional upload targets.
• .vibepresto/auth.json stores workspace-local CLI sessions and is added to .gitignore when possible.
• --workspace-dir <dir> points commands at a different workspace when assets live outside the directory that contains config/auth.

Minimal config shape:

{
  "schemaVersion": 1,
  "project": {
    "name": "marketing-page",
    "projectDir": ".",
    "outputDir": "dist"
  },
  "defaults": {
    "entryHtml": "index.html"
  },
  "defaultEnvironment": "local",
  "environments": {
    "local": {
      "site": "https://your-site.example",
      "uploadTarget": {
        "pageId": 123
      }
    }
  }
}

Core Commands

npx vibepresto login
npx vibepresto whoami --json
npx vibepresto logout --revoke

npx vibepresto upload --site-dir ./dist --json
npx vibepresto upload --zip ./dist.zip --page-id 123 --json

npx vibepresto bundles list --json
npx vibepresto bundles versions --bundle-id 12 --json
npx vibepresto bundles rollback --page-id 123 --version 1 --json

upload --page-id assigns the uploaded bundle and activates VibePresto rendering for that page. It does not change the WordPress homepage.

If the HTML entry is not root index.html, set it in config or pass it directly:

npx vibepresto upload --site-dir ./dist --entry-html nested/app.html --json

Local Validation

Before uploading, the CLI checks bundles against the same safety expectations as the plugin:

• no path traversal or absolute paths
• no hidden/system files such as .htaccess, .DS_Store, __MACOSX, or Thumbs.db
• no server-executable extensions such as PHP, phtml, phar, cgi, pl, py, or sh
• bundle file count, per-file size, and total extracted size must stay within VibePresto limits

Uploaded JavaScript is trusted administrator content. The CLI does not sanitize administrator-provided JavaScript.

WordPress Placeholders

The CLI validates VibePresto placeholder attributes in uploaded HTML:

<h1 data-vp-source="post" data-vp-field="post_title">Fallback title</h1>

verify, upload, and deploy include placeholder diagnostics in JSON output.

Advanced Compatibility

These commands remain available for existing workflows, but they are not the default WordPress.org MVP path.

Page and post management:

npx vibepresto pages list --json
npx vibepresto pages create --title "Landing Page" --status draft --json
npx vibepresto pages set-status --page-id 123 --status publish --json
npx vibepresto pages set-homepage --page-id 123 --json
npx vibepresto pages set-posts-page --page-id 456 --json
npx vibepresto pages set-vibepresto --page-id 123 --active --bundle-version-id 18 --json

npx vibepresto posts list --json
npx vibepresto posts set-status --post-id 789 --status publish --json
npx vibepresto posts set-default-template --lineage-id 12 --json

Route-aware deployment:

npx vibepresto deploy --project-dir ./my-app --create-missing-pages --json
npx vibepresto deployments list --json
npx vibepresto deployments show --deployment-id 3 --json
npx vibepresto deployments promote --deployment-id 3 --bundle-version-id 18 --json
npx vibepresto deployments rollback --deployment-id 3 --version 1 --json

Use route-aware deploy only when one static export intentionally maps across multiple WordPress pages. For normal Home/About/Terms sites, upload one bundle per WordPress page.

JSON Output

Success:

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

Failure:

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