Cliq Server

cliq server is a local HTTP + WebSocket server that exposes the cliq engine via an API. It enables programmatic control of pipelines, real-time event streaming, and serves as the backend for the Dashboard. Optionally, it can operate as an A2A agent so other AI systems can invoke cliq pipelines remotely.

---

Quick Start

cliq server start              # default port 4100
cliq server start --port 8080  # custom port
cliq server status             # check if running
cliq server stop               # stop the server

On start, the server writes ~/.cliqrc/server.json containing the PID, port, and auth token. This file is removed on shutdown.

---

Authentication

Every request requires a Bearer token. The token is generated on each start and printed to the terminal.

HTTP:

curl -X POST http://localhost:4100/instances/list/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

WebSocket:

ws://localhost:4100?token=<token>

---

API Reference

All endpoints are POST-only with JSON bodies unless noted otherwise.

Jobs

Endpoint	Body	Description
/jobs/create/	{ instance_id, req_file?, force?, headless? }	Start a pipeline
/jobs/get/	{ instance_id }	Get current pipeline status
/jobs/list/	{}	List all instances with pipeline status
/jobs/phases/	{ instance_id }	Phase-by-phase status
/jobs/log/	{ instance_id, tail? }	Orchestrator log (optionally last N lines)
/jobs/cancel/	{ instance_id }	Cancel a running pipeline

Instances

The server discovers projects from the instance registry stored in ~/.cliqrc/cliq.db (SQLite). Instances are registered automatically by cliq init and removed by cliq clean.

Endpoint	Description
/instances/list/	List all registered instances with validity
/instances/get/	Get instance details — { id }
/instances/remove/	Remove from registry — { id }

Teams

Endpoint	Body	Description
/teams/list/	{}	List all teams across scopes
/teams/get/	{ name }	Team details (roles, phases, gates)
/teams/create/	{ name }	Create a new empty team
/teams/copy/	{ source, name }	Copy an existing team
/teams/delete/	{ name }	Delete a team
/teams/validate/	{ name }	Validate team definition

Integrations

Endpoint	Body	Description
/integrations/list/	{ project_dir? }	List configured integrations
/integrations/get/	{ name, project_dir? }	Get integration config (secrets masked)
/integrations/test/	{ target, project_dir? }	Test connectivity

Settings

Endpoint	Body	Description
/settings/get/	{ instance_id?, scope? }	Get settings (global, project, or resolved)
/settings/update/	{ scope, patch, instance_id? }	Deep-merge patch into settings

Health

These endpoints are unauthenticated, safe for load balancers and Kubernetes probes.

Endpoint	Method	Description
/health/	POST	Returns { status: "ok", pid }
/healthz	GET	Liveness — 200 if process is running
/readyz	GET	Readiness — 200 if database reachable, 503 otherwise

---

WebSocket Events

Connect via WebSocket for live pipeline events. Subscribe to channels:

{ "action": "subscribe", "channel": "job:cliq-abc123" }

Event	Channel	When
phase_done	job:<id>	Agent completes a phase
gate_verdict	job:<id>	Gate produces a verdict
gate_iteration	job:<id>	Gate iteration counter changes
pipeline_status_changed	job:<id>	Pipeline reaches a terminal state
log_update	job:<id>	Orchestrator log appended
signal_changed	job:<id>	Any signal file change

Unsubscribe:

{ "action": "unsubscribe", "channel": "job:cliq-abc123" }

---

Database

By default the server uses SQLite (~/.cliqrc/cliq.db). For multi-replica deployments, set database.url to a PostgreSQL connection string. The server validates the connection on startup and fails fast if unreachable. See Settings.

---

Process Management

• Runs in the foreground. Stop with Ctrl+C or cliq server stop from another terminal.
• Signal handlers (SIGINT, SIGTERM) ensure clean shutdown — server.json is removed and watchers are closed.
• If the server crashes, cliq server status detects the stale server.json and cliq server start cleans it up automatically.

---

Dashboard

When built (npm run build:all), cliq server serves the web dashboard at the root URL. Open http://localhost:<port>/ in a browser. See Dashboard.

---

A2A Agent Mode

When started with --a2a, the server mounts A2A protocol endpoints alongside the API — other AI systems can discover cliq’s capabilities and invoke pipelines via standard A2A messages. See A2A Agent Mode for the full guide.

cliq server start --a2a                # join all active meshes
cliq server start --a2a --mesh prod    # join a specific mesh

---

Logging

Structured JSON Lines logs capture lifecycle events, task dispatch, pipeline orchestration, and more.

{
  "logging": {
    "server_level": "info",
    "core_level": "debug"
  }
}

See Logging for levels, filtering, rotation, and querying.