Loopi CLI

Run and manage your Loopi workflows from the command line.

The CLI connects to the running Loopi desktop app over a local HTTP server:

The Loopi desktop app must be running for the CLI to work.
All execution happens inside the desktop app — the CLI sends commands and streams back logs.
Your workflows, credentials, and browser sessions are shared between the UI and CLI.

Prerequisites

Loopi desktop app running (pnpm start or an installed release)
Node.js 16+ and pnpm (only needed for development builds)

Two ways to invoke the CLI

Method	When to use	Command prefix
`loopi-cli`	Loopi installed as a desktop app	`loopi-cli <command>`
`pnpm run:workflow`	Running Loopi from source	`pnpm run:workflow <command>`

Both support identical commands and options.

loopi-cli is installed to your PATH when the desktop app starts. On Linux/macOS it's placed in /usr/local/bin/ (or ~/.local/bin/). On Windows, it's in %LOCALAPPDATA%\Loopi\.

Quick start

# 1. Make sure the Loopi desktop app is running

# 2. Check the connection
loopi-cli ping

# 3. List your saved workflows
loopi-cli list

# 4. Run a workflow from a JSON file
loopi-cli run my-workflow.json

# 5. Run a saved workflow by ID
loopi-cli run --id abc123

Commands

`ping` — Check connection

loopi-cli ping
# → Loopi is running on port 19542.

`list` — List saved workflows

Shorthand: ls

loopi-cli list

`get <id>` — Print a workflow as JSON

loopi-cli get abc123 > my-workflow.json

`run <file.json>` — Run from a file

loopi-cli run ./docs/examples/github_issue_tracker.json

The CLI streams NDJSON logs back in real time — per‑node status, final variables, and a success/failure summary.

`run --id <id>` — Run a saved workflow

loopi-cli run --id abc123-def456

`create <file.json>` — Import a workflow

Shorthand: import

loopi-cli create ./my-new-workflow.json
# → Workflow created with ID: abc123-def456

`update <id> <file.json>` — Replace a workflow

loopi-cli update abc123 ./updated-workflow.json

`delete <id>` — Delete a workflow

Shorthand: rm

loopi-cli delete abc123

Global options

Option	Description	Default
`--port <port>`	Override the server port	Auto‑discovered or `19542`
`--headless`	Run browser steps in the background	`true`
`--no-headless`	Show the browser window during execution	`false`
`--help`, `-h`	Show help	—

How it works

┌──────────────┐      HTTP (localhost)       ┌─────────────────────┐
│   CLI Tool   │ ─────────────────────────►  │  Loopi Desktop App  │
│  (terminal)  │  POST /run, GET /workflows   │  (Electron)         │
│              │ ◄─────────────────────────   │  Runs workflows     │
└──────────────┘  Streams NDJSON updates      │  Controls browser   │
                                              └─────────────────────┘

When the desktop app starts, it launches a local HTTP server on 127.0.0.1:19542.
The CLI discovers the port by reading a .loopi-port file from the app's data directory.
Commands are sent as HTTP requests; workflow execution streams back real‑time NDJSON logs.
Only accessible from localhost — never exposed to the network.

Port discovery

Platform	Port file location
Linux	`~/.config/loopi/.loopi-port`
macOS	`~/Library/Application Support/loopi/.loopi-port`
Windows	`%APPDATA%/loopi/.loopi-port`

Override with --port <port> or the LOOPI_CLI_PORT environment variable.

REST API

The CLI is a thin wrapper over a local HTTP API. You can call it with curl or any HTTP client.

Method	Endpoint	Description
`GET`	`/ping`	Health check
`POST`	`/run`	Run inline workflow (JSON body with nodes/edges)
`GET`	`/workflows`	List all saved workflows
`GET`	`/workflows/:id`	Get a workflow by ID
`POST`	`/workflows`	Create a new workflow
`PUT`	`/workflows/:id`	Update a workflow
`DELETE`	`/workflows/:id`	Delete a workflow
`POST`	`/workflows/:id/run`	Run a saved workflow

Example:

curl http://127.0.0.1:19542/workflows
curl -X POST http://127.0.0.1:19542/workflows/abc123/run \
  -H "Content-Type: application/json" \
  -d '{"headless": true}'

Troubleshooting

Cannot connect to Loopi — Make sure the desktop app is running and fully loaded. Verify the port with cat ~/.config/loopi/.loopi-port, or pass --port <port> manually.

Workflow not found — Run list to see available IDs. IDs are UUIDs — make sure you're using the full ID.

Validation failed — The JSON may be malformed. Node types must be automationStep, browserConditional, variableConditional, or forEach (not step).

Browser steps flake in headless mode — Some steps need a visible window. Try --no-headless.

Steps Reference — All 86+ step types and fields.
Variables — How typed variables work across steps.
Agents — Let an agent run the workflows on a schedule.

CLI

On this page