Getting Started

Loopress has two parts: a WordPress plugin and a CLI, lps. The CLI version-controls your site’s code and configuration as files in Git, and syncs them with any WordPress environment through the plugin’s REST API. The plugin must be active on the site, lps project config installs it for you if it’s missing.

What you can do with it

• Version WordPress configuration: ACF field groups, custom post types, menus, options, roles and more, stored as JSON files instead of clicked together in wp-admin on each site.
• Deploy custom PHP: hooks, REST API routes and Composer packages without FTP or a custom plugin.
• Move changes between environments: compare, push and promote local, staging and production, and deploy from CI.

Configuration works with either plugin edition, deploying code (hooks, API routes, Composer) needs Loopress Full. Both are free, see the comparison.

Here’s the whole setup, from installing the CLI to the first sync:

Prerequisites

• A WordPress installation (6.0+) with an administrator account
• PHP 8.2+ on the server
• Node.js 22+ on your machine, for the CLI
• A local Chrome, Edge, or Chromium install, only needed for the automatic plugin install below

Quick start

1. Install the CLI

npm install -g @loopress/cli   # or: pnpm add -g @loopress/cli
lps --version

The CLI checks npm in the background (at most once a day, never blocking a command) and prints a notice when a newer version exists. Run the same install command to upgrade: the CLI and the WordPress plugin evolve together, so staying current avoids debugging already-fixed issues.

2. Connect it to your site

lps project config

Enter your WordPress URL, then choose Authorize in my browser (recommended). This opens your WordPress admin and creates an Application Password for you automatically (WordPress 7.0 or later). If it can’t complete, your site runs an older WordPress, or you’d rather enter credentials yourself, the command falls back to manual entry. If you can’t find the Application Passwords section in your WordPress admin, see Application Passwords.

If Loopress Full isn’t active on the site yet, project config offers to install it for you, after a confirmation prompt. When the automatic install can’t complete (some managed hosts block uploads), it falls back to instructions for a manual upload. Concepts details both steps.

3. Initialize your repository

lps init

Run it at the root of your repository. It writes loopress.json, which ties the repository to the project you just configured and says where each kind of file lives. See lps init for the prompts.

4. Run your first sync

The site’s tagline makes a small first example: every WordPress site has one, and the result is easy to check. Options are tracked one by one, so start tracking it:

lps option add blogdescription

It becomes one JSON file:

my-site/
  .gitattributes
  loopress.json
  options/
    blogdescription.json

{
  "autoload": "on",
  "name": "blogdescription",
  "readonly": false,
  "value": "Just another WordPress site"
}

All of it goes into Git: these files are the source of truth from now on. Credentials never do, they stay in your machine’s config.

git add loopress.json .gitattributes options/ && git commit -m "chore: track the site tagline"

Change value in options/blogdescription.json, then push it back and check the site now matches your files:

lps option push
lps option diff   # "Everything is in sync." once the site matches

You can also see the new tagline under Settings → General in wp-admin. Every other resource follows the same pull, edit, push loop.

Before going further, know what these commands do to your files and your site:

• pull mirrors the site: it overwrites local files and removes the ones whose object no longer exists on WordPress, after asking.
• push never deletes by default, and stops rather than overwrite a change made in wp-admin since your last push.
• Most pushes, options included, can be undone with rollback. Pushing to an environment named production asks for confirmation first (--yes in CI).

Beyond options

The same commands exist for each resource (lps acf pull, lps menu push, lps option diff, …), and three commands run them all at once:

lps pull   # everything the project tracks
lps diff   # what differs between your files and the site
lps push   # everything, in dependency order

See Multi-Environment Workflow for what each one covers.

Next steps

• Concepts: projects and environments, --env, dry runs, and how pull and push treat your files
• Multi-Environment Workflow: push, pull and compare everything at once, promote staging to production
• Pick a feature from the sidebar: ACF, Options, Plugins, Custom API Routes, Composer, and more
• Editor Setup: WordPress autocomplete for the PHP files in your repository
• CI/CD Integration: deploy from a pipeline

Want to see it all wired together, including CI and E2E tests? github.com/loopress/demo is a small reference project you can clone.