Cliq Server

cliq server is an HTTP + WebSocket server that exposes the cliq engine via a POST-only REST API. It enables programmatic control of pipelines, real-time event streaming, and serves as the backend for the Dashboard and other API clients. 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 (except health probes and the A2A agent card) requires a Bearer token in the Authorization header.

HTTP:

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

WebSocket:

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

Token types

cliq supports two kinds of bearer tokens:

Type	Lifetime	Storage	Use case
Session token	Until server stops	In-memory + server.json	Local development, CLI tools
Database token	Until revoked	SQLite or PostgreSQL	Production, integrations, A2A clients

On startup, the server generates and prints an ephemeral session token. This is what local tools (CLI, Dashboard) use — no extra setup needed.

For production and persistent integrations, create database tokens that survive server restarts. These are opaque cliq_sk_ prefixed strings stored as SHA-256 hashes in the database.

Managing tokens

Use cliq server token to create, list, and revoke database tokens:

# Create a token (authenticates via session token on the running server)
cliq server token create --label "jira-plugin"

# List all tokens
cliq server token list

# Revoke a token
cliq server token revoke tok_abc123

See the CLI Reference for all subcommands and options.

Environment bootstrap

For containerized or headless deployments, set CLIQ_ADMIN_TOKEN to seed an initial token on startup:

# Generate a token offline
cliq server token generate
# → cliq_sk_a1b2c3d4...

# Set it as the admin token
export CLIQ_ADMIN_TOKEN=cliq_sk_a1b2c3d4...

# Start the server — token is auto-seeded into the database
cliq server start --a2a

The seed is idempotent — if the token already exists in the database, it is not duplicated. Use this token to provision additional service-specific tokens via the REST API or CLI.

Token management API

The server exposes a REST API for programmatic token management. All endpoints require an existing valid token.

Endpoint	Body	Description
POST /tokens/create/	{ "label": "my-service" }	Create a new token (returns plaintext once)
POST /tokens/list/	{}	List all tokens with status
POST /tokens/revoke/	{ "id": "tok_abc123" }	Revoke a token

What is public (no auth required)

Endpoint	Purpose
GET /.well-known/agent-card.json	A2A agent discovery (spec requires public access)
GET /healthz	Kubernetes liveness probe
GET /readyz	Kubernetes readiness probe

---

API Reference

All endpoints are POST-only with JSON bodies unless noted otherwise. The server uses a shared Pipeline class for all execution paths — both internal API requests and A2A tasks run through the same orchestration logic, ensuring consistent behavior for status mapping, event streaming, and settings overrides.

Jobs

Endpoint	Body	Description
/jobs/create/	{ instance_id, req_file?, settings? }	Start a pipeline (runs in background; subscribe via WebSocket for updates)
/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

Every orchestrator — top-level and nested — runs a TeamEventServer on an ephemeral port, writing its address to .cliq/signals/_ws.json. The cliq server connects to each orchestrator’s WebSocket via an InstanceMonitor and bridges events to API clients.

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

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

Event	Channel	When
pipeline_start	job:<id>	Pipeline begins execution
phase_start	job:<id>	A phase begins execution
phase_done	job:<id>	Agent completes a phase
phase_error	job:<id>	A phase encounters an error
gate_verdict	job:<id>	Gate produces a verdict
gate_iteration	job:<id>	Gate iteration counter changes
pipeline_done	job:<id>	Pipeline completes successfully
pipeline_error	job:<id>	Pipeline fails or escalates

Nested pipeline events

When a pipeline contains team phases, events from sub-team orchestrators are relayed upward with prefixed phase names. For example, if a security-audit team phase runs an analyzer sub-phase, the parent receives events with phase: "security-audit.analyzer" and an incremented depth field. This provides full hierarchical visibility without subscribing to each sub-orchestrator individually.

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 WebSocket connections are closed.
• If the server crashes, cliq server status detects the stale server.json and cliq server start cleans it up automatically.

---

CORS

The server includes CORS support so the Dashboard and other browser-based clients can access the API from a different origin. By default all origins are allowed ("*").

To restrict to specific origins:

{
    "server": {
        "cors_origins": ["https://dashboard.example.com", "http://localhost:5173"]
    }
}

---

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.