Headless CLI

Drive the Desktop engine from a terminal — start it, check its health, run a chat turn, and diagnose version drift

The praisonai-desktop CLI drives the same local engine the Desktop app does, from a terminal — no GUI required.

The same agent you run in the app window is reachable from a shell — start the engine, then send it a prompt.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
)
# Same agent, driven from a shell instead of the app window:
#   praisonai-desktop engine start
#   praisonai-desktop chat "Hello"
agent.start("Hello")

Quick Start

1. Start the engine

   Run the engine in the foreground. The port is printed on the first line the socket is bound; --home DIR sets PRAISONAI_DESKTOP_HOME.

   praisonai-desktop engine start

2. Check it's healthy

   In a second terminal, ask the running engine how it’s doing — port, pid, protocol, agents_version, and data_dir.

   praisonai-desktop engine health

   Exits 1 when no engine is running, with a Start one with… hint.

3. Run a chat turn

   Send one prompt and stream the answer to stdout.

   praisonai-desktop chat "What time is it?"

   A turn that ran tools but returned no text prints a named error rather than a blank success — for example 3 tool call(s) ran, but the model returned no text., the exact praisonaiagents 1.7.1 signature.

4. Diagnose version drift

   Print Python, the installed praisonaiagents, the required floor (read from src-tauri/src/provision.rs at runtime — never hardcoded), and the engine’s running state.

   praisonai-desktop doctor

   Exits 1 when the installed SDK is below the floor.

Command Reference

Each subcommand takes --home to point at a specific data directory; chat adds the flags a single turn needs.

engine start

Runs the engine with the current interpreter and prints its port once listening.

engine health

Reads the lockfile, probes /health, and prints the running engine’s status.

chat

Runs one turn against a running engine and streams the answer.

doctor

Reports the installed praisonaiagents against the provisioned floor and the engine’s state.

How It Finds the Running Engine

engine health, chat, and doctor read the lockfile at <data-dir>/engine.lock, then probe /health on the announced port.

A lockfile alone is not proof — a crashed engine leaves one behind. The /health response must report ok: true and a version matching the engine’s PROTOCOL_VERSION, so a recycled port answered by another loopback service is rejected rather than handed your prompt.

Real Usage Flow

A chat turn opens an SSE stream and answers each frame as it arrives.

On a headless turn there is no human to answer the approval gate, so the CLI answers it: --approve allows, otherwise it denies. A denied tool is recoverable; a frozen turn is not.

Common Patterns

Reproduce a desktop bug in one command — start the engine in one shell, chat in another:

praisonai-desktop engine start
# then, in a second terminal:
praisonai-desktop chat "Use a tool and tell me the result"

Gate a CI job on the SDK floor — doctor exits non-zero when the installed version is too low:

praisonai-desktop doctor || exit 1

Run against a throwaway data directory:

praisonai-desktop engine start --home ~/tmp/praisonai-test

Best Practices

Related