Skip to content

CLI daemon

Run Glueprint as a headless background service on any 64-bit Linux, macOS, or Windows machine.

Available on
  • CLI Daemon

The CLI daemon is Glueprint as a long-running background service. Same engine as the desktop — assistants, sessions, routines, the cloud relay — without a graphical interface. Drive it from the portal, the mobile app, or another desktop machine.

Use it when:

  • You want assistants and routines running 24/7 on a server you don’t keep logged in.
  • A laptop closing its lid shouldn’t stop work.
  • You’re running an autonomous fleet of agents on dedicated infrastructure.

At a glance

  • Binary name: glueprint.
  • Platforms: 64-bit Linux, macOS, Windows.
  • Storage: writes to the OS-standard Glueprint data directory (~/.glueprint on Unix; %APPDATA%\Glueprint on Windows).
  • Signals: SIGINT / SIGTERM / SIGHUP all trigger graceful shutdown.

Install

The CLI ships with the desktop installer. After installing the desktop app, the glueprint binary is available on PATH. You can also install it standalone on a headless server — see Install Glueprint.

Quickstart

# Activate the daemon with a key from the portal
glueprint activate --key gp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Start the daemon. Add --http-port to expose local health endpoints.
glueprint run --http-port 7878

# In another shell:
glueprint status
glueprint session list

Stop the daemon with Ctrl+C (or systemctl stop if you’ve installed it as a service).

Command reference

The daemon has these top-level subcommands. Each supports --help for the full flag list.

glueprint run

Start the daemon.

  • --port <PORT> — MCP server port. Default 0 (OS-assigned).
  • --http-port <PORT> — Optional. Opens a small local HTTP server on 127.0.0.1:<PORT> that exposes the monitoring endpoints below. Use this when you want a health-check probe, a Prometheus-style scraper, or a custom script to read the daemon’s state. Omit the flag and no HTTP server starts.
  • --log-level <LEVEL> — trace / debug / info (default) / warn / error.
  • --environment <ENV> — production (default) / staging / local.

A global --verbose flag promotes the log level to debug.

glueprint activate

Register an activation key with the daemon. Same key format as the desktop: gp_ plus 64 hex characters, generated on the portal.

  • --key <KEY> — pass the key directly. Omit to be prompted interactively.
  • --environment <ENV> — target cloud environment.

The key is stored in the OS keychain when available, with a fallback to a credentials file inside the data directory.

glueprint status

Print daemon and system health.

  • --format <FORMAT> — text (default) or json.

Output includes whether the daemon is running, whether an API key is configured, totals per session status, detected agents with versions, and scheduled routine summary.

glueprint agent detect

Detect installed coding agents (Claude Code, Codex, Gemini) and Glueprint companion binaries (MCP, analytics) on PATH.

  • --format <FORMAT> — text (default) or json.

glueprint session list

List sessions on the host.

  • --status <STATUS> — filter to one of running, stopped, completed, failed, ready, waiting, paused, interrupted.
  • --format <FORMAT> — text or json.

glueprint session stop <ID>

Stop a session by id (full UUID or a short prefix).

  • --format <FORMAT> — text or json.

Errors if the session is already in a terminal state.

Starting or resuming a session from the CLI isn’t supported today. Drive new sessions from the portal or mobile (the daemon picks them up over the relay).

glueprint config get [KEY] / glueprint config set <KEY> <VALUE>

Read or update settings. Keys are dot-separated (for example, appearance.theme, notifications.enabled, cloud.environment). get with no key dumps the full config. set only updates existing keys; it does not create new ones. Types are inferred (booleans, integers, floats with a decimal, otherwise strings).

glueprint team (read-only)

Query the local assistant-team cache. Useful for scripts that need to see team membership or task state without hitting the portal.

  • team list — every cached team.
  • team get <TEAM_ID> — team metadata.
  • team members <TEAM_ID> — membership with hierarchy.
  • team board <TEAM_ID> — tasks grouped by status.
  • team tasks <TEAM_ID> [--status <STATE>] — list tasks for a team.

All support --format text|json.

glueprint service

Install the daemon as an OS service so it starts on boot. Default behavior is to install at the user level on the current platform’s service manager (launchd on macOS, systemd on Linux, Task Scheduler on Windows).

  • service install — install as a service. Options: --no-user to install at the system level (requires root), --bin <PATH> to override the binary location, --print-only to print the service definition and the install command without actually modifying the service registry.
  • service uninstall — remove the service. Supports --no-user.
  • service status — report installed / active state. Supports --no-user, --check-both, --format.

HTTP monitoring endpoints

The daemon doesn’t expose a public API. The --http-port flag opens a tiny read-only HTTP server on 127.0.0.1 only so local monitoring tools can ask the daemon what it’s doing without parsing logs or invoking the CLI on every check.

Typical uses:

  • A systemd watchdog or supervisor process that needs a 200 OK to confirm the daemon is alive.
  • A Prometheus / Datadog / similar agent that scrapes session counts and cloud-connection state.
  • A custom script or dashboard that reads /sessions to surface what’s running.

When --http-port is set, three JSON endpoints bind to 127.0.0.1:<PORT>:

  • GET /health — status ("ok"), version, uptime in seconds.
  • GET /sessions — the active session list (id, name, status, project id, created-at).
  • GET /state — cloud connection state, plan, uptime, scheduler active flag, and counts of running / ready / waiting sessions.

Since the server binds to loopback, you reach it from the same machine only — through localhost, an SSH tunnel, or whatever local proxy you’ve set up.

Shutdown behavior

On SIGINT, SIGTERM, or SIGHUP the daemon performs a graceful shutdown:

  1. Stops the scheduler so no new routines fire.
  2. Stops file and git watchers.
  3. Cancels in-progress task runs.
  4. Drains language servers.
  5. Sends SIGTERM to running agent subprocesses, waits 5 seconds, then SIGKILL.
  6. Transitions sessions to Stopped.
  7. Disconnects from the cloud relay.

A second SIGINT short-circuits to immediate exit.

PreviousWhat works on mobile, what's coming
NextPlans