Using Rivet

Quick start

Start with a disposable destination site. Keep your local WordPress environment running while you export or deploy its database.

1. Install the CLI

Install Node.js 22.18 or newer, then install the release package. No npm account is needed.

npm install -g https://github.com/pixelvise/Rivet/releases/download/v0.2.0/rivet-wp-cli-0.2.0.tgz

rivet --help

Rivet is currently distributed through GitHub Releases, not the npm registry.

2. Activate the connector on the destination

Download the connector ZIP. In the live or staging site’s WordPress admin, open Plugins → Add New → Upload Plugin, select the ZIP, and activate it. You do not need the plugin on the local site.

3. Connect from your local installation

cd /path/to/public_html
rivet init
rivet login https://example.com --name production

Use the directory containing wp-load.php and wp-content. For a subdirectory WordPress installation, enter its base URL, such as https://example.com/site, without /wp-admin.

4. Preview, then deploy content files

rivet push --content-only --dry-run
rivet push --content-only

Read the preview before pushing. Rivet asks you to type the complete destination URL and creates a server-side safety snapshot before applying live changes.

Requirements

The connector does not require server SSH access or a MySQL command-line client. Hosting restrictions, REST firewalls, filesystem permissions, and disk limits can still prevent an operation.

Authorization

rivet login https://example.com --name production

1. Rivet checks for a compatible connector.
2. Your browser opens the destination’s wp-admin. Sign in normally if needed.
3. Compare the verification code with the one in your terminal.
4. Approve the device. Rivet saves a per-device credential locally.

Your WordPress password is not sent to the CLI. Authorization requests expire, and approving a device grants powerful site-management access—including code and database replacement. Only approve requests you initiated.

To revoke a device, use Tools → Rivet in wp-admin or run rivet logout --site production. Device grants are stored outside the database and deliberately survive migrations and restores.

rivet login https://example.com --name production --no-browser

Local environments

LocalWP

Rivet matches the installation directory against Local’s registered sites, then detects the PHP runtime and MySQL socket where available. Start the site in Local before exporting its database.

rivet doctor --path "/path/to/site/app/public"
rivet push --path "/path/to/site/app/public" --content-only --dry-run

WordPress Studio

Enable Studio CLI for terminal in Studio’s settings. Rivet detects the site and runs its exporter through Studio’s own WP-CLI runtime. SQLite data is exported for the destination’s MySQL/MariaDB database; the local SQLite file and driver are not deployed.

Other installations

Rivet boots local WordPress using PHP and reads its configured database connection. A directory cannot make an inaccessible container or stopped database reachable. Custom environments can use runtime/socket overrides or an existing Rivet export.

rivet push --database --content-only \
  --php /path/to/php \
  --socket /path/to/mysql.sock

RIVET_LOCAL_HOME overrides LocalWP’s registry directory. RIVET_STUDIO_HOME overrides the Studio registry directory used for detection.

File deployment

rivet push --content-only --dry-run
rivet push --content-only

--content-only includes managed plugins, themes, uploads, MU plugins, and languages. Without this flag, supported WordPress core paths are also considered. Rivet hashes local files, compares them with the server, and transfers only changed files.

Uploads are staged privately in chunks and verified by checksum before committing. Safe-to-repeat network requests have a bounded retry policy. Once committed, a resumable server job backs up the destination and applies changes during maintenance mode.

Automation

Non-interactive deployment requires an explicit URL confirmation. Pin the site name as well, rather than relying on the last selected target.

rivet push --site production --content-only \
  --confirm https://example.com

Previews & progress

What does --dry-run do?

It means preview only. Rivet compares files with the destination and lists the files and tables that would change. It does not upload content, start a deployment job, or replace live files and database tables. With --database, it may create a private temporary local export to inspect the source.

rivet push --content-only --dry-run
rivet push --content-only --dry-run --verbose

Review the output, then remove --dry-run to deploy. --verbose lists every file; the default preview shows totals and a short sample.

Progress has units, not step numbers

Uploading: 250 of 1,095 files — 12.4 MiB of 55.7 MiB total (22%)
Backing up site files: 2,500 of 4,325 files (57%)
Preparing replacement database tables: 1.0 MiB of 2.0 MiB (50%) — 600 rows staged

The label identifies the current phase. The counts and percentages apply to that phase, not the whole deployment. Interactive terminals update a single line; non-interactive logs are throttled. rivet jobs status <job-id> shows the current state.

Update the connector for fewer requests

The 0.2.0 connector accepts batches of up to 20 small files within a 512 KiB payload limit. Backup, file-apply, and restore-prune steps process up to 100 files with the existing two-second batch budget. This reduces request overhead, but actual time still depends on hosting, the network, and the data.

The new CLI remains compatible with the 0.1.0 connector, using single-file requests and phase-only progress. Update the destination plugin to enable batching and detailed counts. Rivet never overwrites its own connector during a normal push.

Database deployment

rivet push --content-only --database --dry-run
rivet push --content-only --database

Rivet exports source tables, imports them under temporary names on the destination, rewrites source URLs and serialized values, and switches the prepared tables into place. Destination installation URLs and selected host settings are preserved. WordPress table prefixes are mapped to the destination.

Selected table groups

rivet push --content-only --tables my_plugin_settings

Use comma-separated table suffixes, without wp_ or another prefix. Known core dependencies must travel together. Arbitrary plugin relationships are not inferred, so selecting tables does not make a migration safe by itself. Remote tables absent from the source are retained during a push.

Export separately

rivet db export /private/path/site.ndjson
rivet push --content-only --database-export /private/path/site.ndjson

The destination export file must not already exist. Rivet exports use NDJSON, not arbitrary SQL dumps. They contain sensitive data: keep them outside public directories and version control.

Backups & recovery

rivet backup create
rivet backup list
rivet backup restore <snapshot-id>

The list shows timestamped snapshot IDs and file/table counts. Running rivet backup restore without an ID displays the available snapshots and asks you to select one. Restore takes a fresh safety snapshot before replacing the database and managed files.

Unlike a push, restore also removes managed files and tables absent from the selected snapshot. Treat a restore as a destructive operation, not a preview.

Interrupted server jobs

rivet jobs status <job-id>
rivet jobs resume <job-id>
rivet jobs cancel <job-id>

The CLI prints a job ID after committing a deployment or starting a backup/restore. If polling stops, resume that job instead of starting a second operation. Cancellation is allowed only before live changes begin. An interrupted job can leave maintenance enabled until it is resumed or safely cancelled.

Multiple sites

rivet login https://staging.example.com --name staging
rivet login https://example.com --name production
rivet sites
rivet use staging
rivet push --site production --content-only --dry-run

--site overrides the active site for one command. The target URL is printed before a deployment, and explicit confirmation is still required for live replacement operations.

rivet logout --site staging

Storage & configuration

Local project exclusions

rivet init creates an optional .rivet.json file. Exclusions are literal path prefixes relative to the WordPress installation—not glob patterns.

{
  "version": 1,
  "exclude": ["wp-content/uploads/private-assets"]
}

Private server storage

The connector chooses a writable directory outside the detected web document root. If that is not possible, configure a private path in the destination’s wp-config.php:

define('RIVET_STORAGE_DIR', '/home/account/.rivet-private');

The path must be outside every public document root and share a filesystem with WordPress so file replacement can use atomic renames. Never place Rivet snapshots in public uploads. The example path is illustrative; verify your own hosting layout.

Device credentials

CLI profiles are stored with restrictive permissions in ~/.config/rivet. Set RIVET_CONFIG_DIR to override that location. Do not put credentials, exports, or private backup directories into a repository.

Command reference

Run rivet --help for flags including --path, --site, --content-only, --database, --tables, --dry-run, and --confirm.

Release boundaries

Rivet v0.2.0 is an early release. Use a disposable site to validate your environment before relying on it for production work.

• No row-level merge. Database pushes replace selected tables, including local/live differences within them.
• Single-site WordPress only. Multisite is not supported.
• Schema restrictions. Views, triggers, foreign-key dependencies, and generated-column schemas are unsupported. Individual exported records are limited to 8 MiB.
• Application-level maintenance. It is not a database-wide lock. Pause external writers, host cron, and other processes that can modify data during a migration.
• No atomic whole-site release. File application spans multiple steps. A deployed PHP fatal error can stop WordPress and its REST connector; recovery then requires hosting/file access.
• Upload and job recovery differ. Individual upload requests can retry safely, but restarting a failed staging upload currently requires a new push. Committed server jobs can be resumed by ID.
• Storage requires attention. Snapshots and staging data consume server disk. There is no retention/download command yet.
• Compatibility is not universal. Large sites, unusual hosting layouts, custom database drop-ins, and plugin combinations need their own validation.

Build from source

git clone https://github.com/pixelvise/Rivet.git
cd Rivet
npm ci
npm run check
npm link
npm run plugin:zip

The CLI is TypeScript compiled to JavaScript, with no runtime npm dependencies. The connector is PHP. This documentation site is a separate Next.js static export.

npm run test:package
npm run test:integration
RIVET_TEST_STUDIO=1 npm run test:integration

Integration tests require PHP with mysqli, MySQL server tools, and tar. They create isolated WordPress/database fixtures. Studio coverage additionally requires Studio CLI.

npm --prefix website ci
npm run site:dev
npm run site:build

Created by Craig Gomes. Contributions are welcome under the MIT license. Keep bug reports reproducible and remove credentials, database exports, and private site details before sharing them.