The local-cli is dead. Long live local-cli [A LocalWP Addon to resurrect local-cli].

Some of you might remember lbl, my handy little “missing CLI for Local” script from a few years back. Starting, stopping and restarting sites in that script leaned on @getflywheel/local-cli, the official command line tool from the Local folks.

Leaned. Past tense.

Because that tool is deprecated. It talks to Local’s GraphQL server, and that conversation has become… let’s call it “unreliable”. And on the days it did work, it only worked if your shell happened to be on the right Node version. cd into a project with an .nvmrc, and poof; a stack trace, or a Node that runs in an x86 container and can’t even reach Local anymore.

I have a zsh function that starts the site of the folder I cd into. It has been throwing errors lately. I needed a fix … get it? … a f…. never mind, I’ll see myself out.

This is Addon number 8 of 7 ;)

The Problem

Local has no supported way to control sites from the command line. There is the deprecated local-cli, which is GraphQL and Node-based. Since Local-CLI is deprecated, there is nothing stopping the LocalWP team from silently discontinuing the GraphQL API. So I created my own.

And I am, as stated before, a terminal type of person. I want local-cli start-site mysite to just… start the site. From a shell script, from a cron job, from a CI runner, from that zsh function. Without caring which Node is active, or whether Node is active at all.

So what do we do about it?

Once again, everything needed is already in the pantry;

• An addon runs inside Local’s own main process, and gets handed the same siteProcessManager the Start and Stop buttons in the UI use. No GraphQL required.
• Node (the one inside Local, the only one that matters here) can open an HTTP server on a Unix domain socket. No TCP port, no token; the file permissions on the socket are the authentication. Only the user running Local can talk to it.
• curl speaks Unix sockets. curl is everywhere. And curl has never once been broken by nvm.

So the client side doesn’t need Node at all. A plain POSIX shell script, a curl call, done. Glue was applied. ;)

The Solution

CLI Bridge: a Local addon that runs a tiny HTTP server on a Unix socket inside Local, plus a local-cli shell script that talks to it. It is a drop-in replacement for the deprecated tool; same command names, same ID | Name | Status table, so scripts written against the old local-cli keep working. Mine did, without changing a single line.

A site can be referenced by its ID, its domain or its name, case-insensitive. A unique prefix works too; an ambiguous prefix lists the candidates and refuses to guess.

The details that make it actually usable;

• Add --json for the raw response (ideal for jq) or --plain for tab-separated ID Name Domain Status (ideal for cut/awk).
• Starting a site that is already running, or stopping one that is already halted, is a successful no-op. Start/stop/restart return once Local reports the transition finished, typically within a few seconds.
• Proper exit codes: 0 ok, 1 the command failed (unknown site, Local refused), 2 Local or the addon is not reachable, 64 you typed it wrong.
• Start/stop go through Local’s own machinery, exactly the code path the buttons use. Local’s UI updates as if you clicked. Because, in a way, you did.
• Don’t like the script? Talk to the bridge directly: curl --unix-socket ~/.local-cli-bridge/bridge.sock -X POST http://local/sites/wp/start
• Socket and bookkeeping live in ~/.local-cli-bridge/ (mode 0700/0600) and are cleaned up when Local quits. On Windows it’s a named pipe; untested by me, so please, tell me what happens.

Adding a command later is one route in the addon and one line in the shell script’s case. PRs welcome, as always.

Full transparency on quality assurance; tested by 1 person on Local 10.1.2. The addon only touches siteData, siteProcessManager and localLogger, which are identical in Local 9, so it should work there too. Feel free to confirm or deny.

Get it

Source on GitHub: rmpel/Local-CLI-Bridge. Be sure to read the notes.

Install from source (MacOS and Linux);

Restart Local to make it visible in the Installed addons list, toggle on as usual, restart Local once more when it asks you to, and run local-cli ping.

Install from a dist file (All OS); grab the latest .tgz from the dist folder, or build it with ./scripts/build.sh, and use the “Install from disk” feature in LocalWP. You’ll still need the bin/local-cli script somewhere on your PATH.

One gotcha; if you still have the deprecated npm package installed, it usually sits earlier on your PATH and shadows the new command. The installer warns you about it. Get rid of it with npm uninstall -g @getflywheel/local-cli. You won’t miss it.