Settings

Cliq determines its configuration and settings from two settings.json files. One exists at the globel level at ~/.cliqrc/settings.json and the other at the project level at .cliq/settings.json in the project directory. Thus, settings exist at two levels with project settings overriding global settings via deep merge.

Location	Scope	Created by
`~/.cliqrc/settings.json`	Global — applies to all projects	`cliq init` (first run)
`.cliq/settings.json`	Project — overrides global for this project	`cliq init` / `cliq assemble`

Project settings files are gitignored by default.

Managing settings can be done either on the command line with the cliq settings command or by editing the JSON directly. If you edit by hand it is highly recommended to run validation after editing by running cliq doctor.

Tutorial: Using `cliq settings`

The cliq settings command is the recommended way to read, write, and explore configuration. It validates keys, coerces types, masks secrets, and keeps your JSON well-formed. This walkthrough covers the most common operations.

Explore the schema

Start by discovering what’s available. cliq settings --info prints every top-level section with a one-line summary:

cliq settings --info

cliq settings

  default_agent   Default agent for phases without an explicit agent: field.
  notifications   Event-driven notification routing to channels.
  headless        Run orchestrator in foreground instead of tmux.
  hub             CliqHub team registry URL and token.
  logging         Structured server logging configuration.
  agents          Per-agent configuration — settings, custom entry points, and host env declarations.
  server          Server port, A2A agent mode, mesh connections.
  builder         LLM provider for AI team generation.
  docker          Container isolation settings.
  database        Storage backend (SQLite or PostgreSQL).
  kubernetes      Kubernetes Job-based pipeline execution.
  strict_input_validation  Reject unknown team inputs in headless/A2A mode.

Run 'cliq settings <section> --info' for additional info on a section.

Drill into any section to see its fields:

cliq settings agents.git.github --info

agents.git.github

  token           GitHub Personal Access Token (string, secret)
  base_branch     Branch to create feature branches from (string, default: "main")
  remote          Git remote name (string, default: "origin")
  pr_draft        Create PRs as drafts (boolean, default: false)
  pr_reviewers    GitHub usernames to request review from (string[])
  pr_labels       Labels to apply to created PRs (string[])

Run 'cliq settings agents.git.github.<keyname> --info' for additional info on <keyname>.

Read settings

Read the merged (resolved) value of any key using dot notation:

cliq settings agents.git.github.base_branch
# → main

cliq settings default_agent
# → cursor

Read an entire section to see all its values:

cliq settings agents.git.github

List all resolved settings (global merged with project):

cliq settings

List only global settings:

cliq settings --global

Write settings

Set a value at the project level (the default when inside a project directory):

cliq settings agents.git.github.base_branch develop

Set a value at the global level:

cliq settings agents.git.github.base_branch main --global

Booleans and numbers are coerced automatically:

cliq settings headless true
cliq settings docker.max_containers 8 --global

Handle secrets safely

Credential fields are masked by default. Use --stdin to avoid secrets appearing in shell history:

echo $GITHUB_TOKEN | cliq settings agents.git.github.token --stdin --global

Read a masked value:

cliq settings agents.git.github.token --global
# → ghp_x****

Reveal the full value:

cliq settings agents.git.github.token --global --unmask
# → ghp_xxxxxxxxxxxx

Work with arrays

Use --add and --remove for array fields:

cliq settings --add agents.git.github.pr_labels needs-review
cliq settings --remove agents.git.github.pr_labels auto

Remove a key

Unset a key to fall back to the global value (in project settings) or the default (in global settings):

cliq settings --unset agents.git.github.pr_draft

A typical setup session

Here’s what a first-time configuration looks like:

# Set your default agent
cliq settings default_agent claude-code --global

# Configure GitHub integration
echo $GITHUB_TOKEN | cliq settings agents.git.github.token --stdin --global
cliq settings agents.git.github.base_branch main --global

# Configure Slack notifications
echo $SLACK_WEBHOOK | cliq settings agents.slack.channels.default.webhook_url --stdin --global

# Configure the Builder LLM
cliq settings builder.provider google --global
echo $GEMINI_API_KEY | cliq settings builder.api_key --stdin --global
cliq settings builder.model gemini-2.5-pro --global

# Verify everything works
cliq doctor

For project-specific overrides, drop the --global flag inside a project directory:

cd ~/my-project
cliq settings agents.git.github.base_branch develop
cliq settings agents.git.github.pr_draft true

See cliq settings CLI Reference for the complete option reference.

How Settings Merging Works

When any cliq command runs, it deep-merges global and project settings in memory. The merged result is used for the duration of the command — no intermediate file is written to disk.

Project values override global values at the leaf level
Empty strings in the project file override global values — only omit a key to inherit the global value
Arrays are replaced, not merged

Example

Global (~/.cliqrc/settings.json):

{
  "agents": {
    "git": {
      "github": { "token": "ghp_secret", "base_branch": "main", "pr_labels": ["auto"] }
    }
  }
}

Project (.cliq/settings.json):

{
  "agents": {
    "git": {
      "github": { "base_branch": "develop" }
    }
  }
}

Merged result (in memory):

{
  "agents": {
    "git": {
      "github": { "token": "ghp_secret", "base_branch": "develop", "pr_labels": ["auto"] }
    }
  }
}

The token is inherited from global; base_branch is overridden by project. Use cliq settings inside a project directory to inspect the merged result.

Per-Run Override (`cliq run --settings`)

For one-off, programmatic, per-invocation customization, cliq run accepts an additional settings file that is merged on top of the global + project layers as the highest-precedence layer:

cliq run --settings ./prod.json
cliq run --settings /etc/cliq/silent.json

The override file is a regular settings JSON file (full or partial) and is applied only for that one invocation. Nothing is persisted to disk; no project state is modified.

Precedence

~/.cliqrc/settings.json              (global,   lowest precedence)
       ↓ deep merge
<workspace>/.cliq/settings.json      (project)
       ↓ deep merge
<path>  via --settings <path>        (override, highest precedence,
                                      present only when --settings was passed)
       ↓
final merged settings used by this run

The same deep-merge semantics apply at every level — nested objects merge recursively, arrays replace, and empty strings in higher layers win over lower layers.

When to use it

A2A integrations dispatching tickets that need ticket-specific notification routes for a single run (no shared file mutation, no concurrent-dispatch races).
Test harnesses / CI suppressing notifications without editing project state, e.g. cliq run --settings ./test/silent.json.
Operations layering per-environment overrides like log level or model choice, e.g. cliq run --settings /etc/cliq/prod.json.
Manager-style team phases (future) injecting per-child team settings.

Behavior

Scenario	Behavior
Flag absent	Current behavior, no override (global + project only).
Flag with relative path	Resolved against the current working directory.
Flag with non-existent file	Run aborts at first settings load with `Settings override file not found: <path>`.
Flag with malformed JSON	Run aborts with the file path and JSON parse error.
Flag with unknown / mistyped keys	Run aborts with the same validation report used for project/global settings.

Scope and propagation

The override applies to the orchestrator, every agent pane, the headless child process, and any container/Job spawned by the run.
Recursive type: team phases inherit the override automatically — the sub-pipeline sees the same merged settings as its parent.
The override does not affect cliq doctor, cliq settings, or any read-only command run independently in the same shell. It is scoped to one cliq run.
The override does not cross the A2A boundary into out-of-process child teams. A2A-dispatched children require explicit forwarding with allowlist filtering, which is an A2A-executor concern.

Audit log

When the override is active, cliq run emits a structured log line at run start naming the override file and listing its top-level sections:

Settings override active: /abs/path/to/prod.json (keys: notifications, logging)

Section values are never logged — top-level keys only — because content is often sensitive (channel IDs, recipient emails, tokens).

Advanced: setting the env var directly

--settings <path> is implemented by exporting the absolute path as CLIQ_SETTINGS_OVERRIDE before any settings load. Setting the env var directly produces the same effect:

CLIQ_SETTINGS_OVERRIDE=/abs/prod.json cliq run

This is useful for downstream callers (CI scripts, A2A executors, container entrypoints) that prefer environment over CLI flags.

Quick Reference

Section	Description
`default_agent`	Default agent for phases without an explicit `agent:` field
`notifications`	Event-driven notification routing to channels
`headless`	Run orchestrator in foreground instead of tmux
`hub`	CliqHub team registry URL and token
`logging`	Structured server logging levels, rotation, and directory
`agents`	Per-agent configuration — settings, custom entry points, and host env declarations
`server`	Server port, A2A agent mode, mesh connections, and workflow streaming
`builder`	LLM provider for AI team generation
`docker`	Container isolation settings
`database`	Storage backend (SQLite or PostgreSQL)
`kubernetes`	Kubernetes Job-based pipeline execution
`strict_input_validation`	Reject unknown team inputs in headless/A2A mode

Complete Settings Example

Every section with realistic values. Fields with empty strings ("") are placeholders — fill them with your own credentials.

{
  "default_agent": "cursor",
  "notifications": {
    "on_start":          { "channels": ["slack"] },
    "on_phase_start":    { "channels": [] },
    "on_phase_complete": { "channels": [] },
    "on_complete":       { "channels": ["slack"] },
    "on_escalate":       { "channels": ["slack"] },
    "on_cancel":         { "channels": ["slack"] }
  },
  "headless": false,
  "hub": {
    "registry_url": "https://cliqhub.io"
  },
  "logging": {
    "server_level": "info",
    "core_level": "info",
    "component_levels": {},
    "dir": "",
    "max_file_size_mb": 50,
    "max_files": 5
  },
  "agents": {
    "git": {
      "github": {
        "base_branch": "main",
        "remote": "origin",
        "token": "ghp_xxxxxxxxxxxx",
        "pr_draft": false,
        "pr_reviewers": ["teammate"],
        "pr_labels": ["cliq-generated"]
      },
      "bitbucket": {
        "workspace": "my-workspace",
        "email": "[email protected]",
        "api_token": "ATBB...",
        "base_url": "https://api.bitbucket.org/2.0"
      }
    },
    "cursor": {
      "api_key": "key_abc123..."
    },
    "jira": {
      "base_url": "https://your-org.atlassian.net",
      "email": "[email protected]",
      "api_token": "ATATT3x..."
    },
    "slack": {
      "channels": {
        "default": { "webhook_url": "https://hooks.slack.com/services/T.../B.../xxx" }
      }
    },
    "email": {
      "smtp_host": "smtp.example.com",
      "smtp_port": 587,
      "from_address": "[email protected]",
      "channels": {
        "default": ["[email protected]"]
      }
    },
    "hug": {
      "server_url": "https://hug.example.com",
      "token": "hug-auth-token",
      "enable_chat": true,
      "llm": {
        "provider": "anthropic"
      },
      "reviewers": [
        { "name": "alice", "channels": ["slack:alice"] },
        { "name": "architects", "members": ["alice"], "policy": "any" }
      ]
    },
    "gdrive": {
      "credentials_file": "/path/to/service-account.json"
    },
    "onedrive": {
      "tenant_id": "your-azure-tenant-id",
      "client_id": "your-client-id",
      "client_secret": "your-client-secret"
    }
  },
  "server": {
    "port": 4100,
    "a2a": {
      "agent_type": "cliq_pipeline",
      "instance_id": "cliq-macbook-01",
      "workspace_root": "/tmp/cliq-workspaces",
      "public_url": "https://abc123.ngrok.io",
      "meshes": [
        {
          "name": "savant-prod",
          "type": "savant",
          "active": true,
          "url": "https://savant.example.com",
          "client_id": "cliq-agent",
          "client_secret": "your-secret"
        }
      ],
      "advertise": ["build_team", "run_pipeline"],
      "enable_builder": false
    },
    "workflow_streaming": {
      "enabled": "auto",
      "interval_seconds": 5,
      "max_lines": null
    }
  },
  "builder": {
    "provider": "openai",
    "api_key": "sk-...",
    "model": "gpt-4o",
    "api_url": "https://api.openai.com/v1/chat/completions"
  },
  "docker": {
    "enabled": false,
    "image": "ghcr.io/elanamir/cliq-runner:latest",
    "memory": "4g",
    "cpus": "2",
    "network_mode": "bridge",
    "read_only_rootfs": true,
    "max_containers": 4,
    "extra_hosts": [],
    "env": {}
  },
  "database": {
    "url": ""
  },
  "kubernetes": {
    "enabled": false,
    "namespace": "cliq",
    "workspace_pvc": "cliq-workspaces",
    "config_configmap": "cliq-config",
    "api_key_secret": "cliq-secrets",
    "api_key_secret_key": "cursor-api-key",
    "service_account": "cliq-runner",
    "node_selector": {},
    "tolerations": [],
    "ttl_after_finished": 300
  },
  "strict_input_validation": false
}

default_agent

Field	Type	Default	Description
`default_agent`	string	`"cursor"`	Default agent for phases that don’t specify an explicit `agent:` field in `team.yml`

Phases without an agent: field use this agent at runtime. The setting is available at both global and project scope — set it globally to change your default across all projects, or per-project to use a different agent for a specific codebase.

{
    "default_agent": "gemini-api"
}

Built-in agents: cursor, claude-code, gemini, codex, hug. Custom agents declared in team.yml or settings can also be used. See Cliq SDK — Choosing an Agent for details.

cliq settings default_agent gemini-api --global

Notifications

Event-driven notification routing. Each key corresponds to a pipeline lifecycle event.

Event	Fires when
`on_start`	Pipeline begins execution
`on_phase_start`	A phase begins execution
`on_phase_complete`	A phase finishes successfully
`on_complete`	Pipeline completes all phases
`on_escalate`	A gate exhausts iterations and escalates
`on_cancel`	User cancels via Ctrl-C, SIGTERM, or SIGHUP

Each event accepts a NotificationEventConfig object:

Field	Type	Default	Description
`channels`	string[]	`[]`	Channel references to notify (e.g., `["slack", "slack:incidents", "email:ops"]`)

Use colon notation to target named channels within an agent (e.g. "slack:incidents" resolves to agents.slack.channels.incidents).

{
  "notifications": {
    "on_start": {
      "channels": ["slack"]
    },
    "on_complete": {
      "channels": ["slack"]
    },
    "on_escalate": {
      "channels": ["slack:incidents"]
    },
    "on_cancel": {
      "channels": ["slack"]
    }
  }
}

See Notifications for the full guide on channel routing and message formatting.

headless

Field	Type	Default	Description
`headless`	boolean	`false`	Run orchestrator in the foreground terminal instead of inside tmux

When true, the orchestrator runs in the current terminal and agents run in a detached background tmux session. Equivalent to cliq run --headless. The CLI flag takes precedence.

{
  "headless": true
}

hub

Configuration for the CliqHub team registry. Used by cliq team and cliq hub commands for team resolution, publishing, and installation. See CliqHub for browsing teams and publishing.

Field	Type	Default	Description
`registry_url`	string	`"https://cliqhub.io"`	Base URL of the CliqHub registry
`token`	string	`""`	Authentication JWT. Managed automatically by `cliq hub login`

Browsing, searching, and installing are anonymous — no token required. A token is only needed for publishing teams. For CI/CD, generate a named API token with cliq hub token.

{
  "hub": {
    "registry_url": "https://cliqhub.io",
    "token": "cliqhub_tok_xxxx"
  }
}

logging

Configuration for structured server logging. Logs are written as JSON Lines when cliq server is running. See Logging for the full guide — levels, components, rotation, and query examples.

Field	Type	Default	Description
`server_level`	LogLevel	`"info"`	Log level for server components (`server`, `a2a`, `mesh`)
`core_level`	LogLevel	Same as `server_level`	Log level for core engine components (`orchestrator`, `pipeline`, `signal`, `gate`, etc.). Inherits from `server_level` when omitted
`component_levels`	Record<string, LogLevel>	`{}`	Per-component level overrides. Takes precedence over both `server_level` and `core_level`
`dir`	string	Auto	Log directory. Tries `/var/log/cliq/` first, falls back to `~/.cliqrc/logs/`
`max_file_size_mb`	number	`50`	Maximum log file size before rotation (MB)
`max_files`	number	`5`	Number of rotated log files to retain

LogLevel values (from most to least verbose): trace | debug | info | warn | error

Example — verbose core logging, quiet server:

{
  "logging": {
    "server_level": "warn",
    "core_level": "debug",
    "component_levels": {
      "mesh": "trace",
      "gate": "debug"
    },
    "max_file_size_mb": 100,
    "max_files": 10
  }
}

agents

Flat map of agent name to configuration. Each entry holds the agent’s settings (API keys, credentials, service URLs), and optionally a custom entry point. See Cliq SDK for the full guide on built-in agents, choosing an agent, and building custom agents.

The agents key is a Record<string, AgentConfig> where each value has:

Field	Type	Required	Description
`entry`	string	no	Custom entry point JS file (overrides the builtin agent)
`api_key`	string	no	Agent API key (for CLI and LLM API agents)
any key	unknown	no	Arbitrary agent-specific settings (e.g. `base_url`, `email`, `credentials_file`)

Phases reference agents by name in team.yml via the agent field. When a phase doesn’t specify an agent, default_agent is used.

Per-agent settings are scoped — each agent only receives the keys declared in its manifest settings.required / settings.optional at runtime via ctx.settings. Use cliq setup to configure these interactively, or set them directly:

cliq settings agents.jira.api_token "..."
cliq settings agents.cursor.api_key "key_abc123..."

Built-in agents declare their required settings keys in their manifest.json. cliq doctor and cliq assemble validate that all required settings are present before a run starts.

{
    "default_agent": "gemini-api",
    "agents": {
        "jira": {
            "base_url": "https://acme.atlassian.net",
            "email": "[email protected]",
            "api_token": "..."
        },
        "cursor": {
            "api_key": "key_abc123...",
            "entry": "path/to/custom_cursor.js"
        }
    }
}

agents.git.github

GitHub settings are configured under the git agent. These control branching, PR creation, and authentication for GitHub-hosted repositories.

Field	Type	Default	Description
`token`	string	`""`	GitHub Personal Access Token
`base_branch`	string	`"main"`	Branch to create feature branches from
`remote`	string	`"origin"`	Git remote name
`pr_draft`	boolean	`false`	Create PRs as drafts
`pr_reviewers`	string[]	`[]`	GitHub usernames to request review from
`pr_labels`	string[]	`["cliq-generated"]`	Labels to apply to created PRs

See Git Agent for setup.

agents.git.bitbucket

Bitbucket settings are configured under the git agent. These control authentication and API access for Bitbucket-hosted repositories.

Field	Type	Default	Description
`workspace`	string	`""`	Bitbucket workspace slug
`email`	string	`""`	Atlassian account email
`api_token`	string	`""`	Bitbucket API token (Repos R/W + PRs R/W)
`base_url`	string	`"https://api.bitbucket.org/2.0"`	API base URL

See Git Agent for setup.

agents.jira

Jira credentials and configuration. For step-by-step setup, see the Jira Agent page.

Field	Type	Default	Description
`base_url`	string	`""`	Jira instance URL
`email`	string	`""`	Atlassian account email
`api_token`	string	`""`	Jira API token

cliq settings agents.jira.base_url "https://your-org.atlassian.net" --global
cliq settings agents.jira.email "[email protected]" --global
echo $JIRA_TOKEN | cliq settings agents.jira.api_token --stdin --global

agents.slack

Slack webhook configuration. For step-by-step setup, see the Slack Agent page.

Field	Type	Default	Description
`channels`	object	`{}`	Named channels, each with a `webhook_url`

All Slack webhooks are defined under named channels. Use default for the bare "slack" channel reference:

{
  "agents": {
    "slack": {
      "channels": {
        "default": { "webhook_url": "https://hooks.slack.com/services/.../default" },
        "elan": { "webhook_url": "https://hooks.slack.com/services/.../elan" },
        "incidents": { "webhook_url": "https://hooks.slack.com/services/.../incidents" }
      }
    }
  }
}

Reference channels in notification configs and hug reviewer settings:

"slack" — resolves to channels.default.webhook_url
"slack:elan" — resolves to channels.elan.webhook_url
"slack:incidents" — resolves to channels.incidents.webhook_url

agents.email

Email notification configuration via SMTP. For step-by-step setup, see the Email Agent page.

Field	Type	Default	Description
`smtp_host`	string	`""`	SMTP server hostname
`smtp_port`	number	`587`	SMTP server port
`username`	string	`""`	SMTP authentication username
`password`	string	`""`	SMTP authentication password
`tls`	boolean	`true`	Use STARTTLS
`from_address`	string	`""`	Sender email address (From: header)
`from_name`	string	`""`	Sender display name (optional)
`channels`	object	`{}`	Named channels, each mapping to a list of recipient addresses

Configure your SMTP server globally, then define named channels with recipient lists:

{
  "agents": {
    "email": {
      "smtp_host": "smtp.example.com",
      "smtp_port": 587,
      "username": "[email protected]",
      "password": "smtp-password",
      "tls": true,
      "from_address": "[email protected]",
      "from_name": "Cliq Alerts",
      "channels": {
        "default": ["[email protected]"],
        "ops": ["[email protected]", "[email protected]"],
        "leads": ["[email protected]"]
      }
    }
  }
}

Reference channels the same way as Slack:

"email" — resolves to channels.default recipients
"email:ops" — resolves to channels.ops recipients
"email:leads" — resolves to channels.leads recipients

Emails include both HTML and plain text versions. HTML uses inline styles for compatibility with Gmail, Outlook, and Apple Mail.

Retry behavior matches Slack webhooks: up to 3 attempts with exponential backoff on transient SMTP errors. Permanent failures (5xx, auth errors) are not retried.

HUG (Human Gate)

The HUG agent is configured under agents.hug. This includes server connection, reviewer routing, and chat settings. See Human Gate (HUG) for an overview.

{
    "agents": {
        "hug": {
            "server_url": "https://hug.example.com",
            "token": "hug-auth-token",
            "enable_chat": true,
            "llm": { "provider": "anthropic" },
            "reviewers": [
                { "name": "alice", "channels": ["slack:alice"] },
                { "name": "architects", "members": ["alice"], "policy": "any" }
            ]
        }
    }
}

Google Drive

The gdrive agent is configured under agents.gdrive:

{
    "agents": {
        "gdrive": {
            "credentials_file": "/path/to/service-account.json"
        }
    }
}

See Google Drive Agent for setup.

Microsoft OneDrive

The onedrive agent is configured under agents.onedrive:

{
    "agents": {
        "onedrive": {
            "tenant_id": "your-azure-tenant-id",
            "client_id": "your-client-id",
            "client_secret": "your-client-secret"
        }
    }
}

See OneDrive Agent for setup.

Custom Agents

Custom agents are declared in team.yml and built with the Cliq SDK (@cliqhub/cliq-sdk). Each entry in the agents block of team.yml has a uniform shape:

Field	Type	Required	Description
`entry`	string	yes	Path to the agent entry point script

agents:
  qa-agent:
    entry: agents/qa/index.js

Set the agent’s settings values in settings.json under agents.<name>:

{
    "agents": {
        "qa-agent": {
            "api_key": "key_..."
        }
    }
}

server

Configuration for the cliq server (API, CORS, and A2A agent mode). See Cliq Server and A2A Protocol for full details.

Field	Type	Default	Description
`port`	number	`4100`	HTTP port for the cliq server. Overridden by `--port` CLI flag
`cors_origins`	string \| string[]	`"*"`	Allowed CORS origins. `"*"` allows all origins. A string or array restricts to specific origins
`settings_allowlist`	string[]	`["notifications", "logging"]`	Dot-path allowlist for external settings overrides (via `--settings`). Only keys matching these prefixes are accepted from override files

server.a2a

A2A agent mode settings. Only needed if cliq participates in an agent mesh.

Field	Type	Default	Description
`agent_type`	string	`"cliq_pipeline"`	Logical agent type for mesh routing. All cliq instances share this value
`instance_id`	string	`""`	Unique instance identifier. Must be unique across all cliq instances in a mesh
`workspace_root`	string	`"/tmp/cliq-workspaces"`	Directory where temporary task workspaces are created. Cleaned up after each task
`public_url`	string	`""`	Public URL for the agent card and mesh registration (e.g., an ngrok tunnel). Overridden by `--public-url` CLI flag. When empty, defaults to `http://localhost:<port>`
`meshes`	A2aMeshConfig[]	`[]`	Array of mesh connections (see below)
`advertise`	string[]	—	List of capability names to advertise to the mesh. When omitted, all capabilities are advertised
`enable_builder`	boolean	`false`	Enable builder capabilities (`build_team`, `generate_role`, `improve_role`, `validate_team`). When `false`, these skills are hidden from the agent card and rejected at runtime

server.a2a.meshes[]

Each entry configures a connection to an agent mesh network.

Field	Type	Description
`name`	string	Human-readable name for this mesh (used with `--mesh` CLI flag)
`type`	`"savant"`	Mesh protocol type. Currently only `"savant"` is supported
`active`	boolean	Whether this mesh is joined when `--a2a` is used without `--mesh`
`url`	string	URL of the mesh node (e.g., Savant server)
`client_id`	string	Client ID for mesh authentication
`client_secret`	string	Client secret for mesh authentication

Example — two meshes, one active by default:

{
  "server": {
    "port": 4100,
    "a2a": {
      "agent_type": "cliq_pipeline",
      "instance_id": "cliq-macbook-01",
      "workspace_root": "/tmp/cliq-workspaces",
      "public_url": "https://abc123.ngrok.io",
      "meshes": [
        {
          "name": "savant-prod",
          "type": "savant",
          "active": true,
          "url": "https://savant.example.com",
          "client_id": "cliq-agent",
          "client_secret": "your-secret"
        },
        {
          "name": "savant-staging",
          "type": "savant",
          "active": false,
          "url": "https://savant-staging.example.com",
          "client_id": "cliq-agent",
          "client_secret": "staging-secret"
        }
      ],
      "advertise": ["run_pipeline", "build_team"],
      "enable_builder": true
    }
  }
}

cliq server start --a2a joins savant-prod (active). cliq server start --a2a --mesh savant-staging joins only staging regardless of the active flag.

server.workflow_streaming

Controls live streaming of workflow execution to the A2A event bridge and the dashboard’s Phase Output panel. When active, the orchestrator streams agent output, check results, and preflight results in real time. Output is preserved after the pipeline ends so the last phase’s state remains visible. See Dashboard for the Phase Output panel.

Field	Type	Default	Description
`enabled`	`"auto"` \| `true` \| `false`	`"auto"`	`"auto"` activates capture when an A2A task is running or the cliq server is running. `true` always captures. `false` never captures
`interval_seconds`	number	`5`	How often (in seconds) the flush loop writes accumulated output to the A2A event bridge
`max_lines`	number \| null	`null`	Maximum lines per flush event. `null` means unlimited — all output since the last flush is sent

{
  "server": {
    "workflow_streaming": {
      "enabled": "auto",
      "interval_seconds": 5,
      "max_lines": null
    }
  }
}

With "auto", local cliq run sessions incur zero capture overhead. Capture activates automatically when the cliq server or an A2A task is present. Set to true if you want to monitor output via the dashboard even without A2A.

builder

Configuration for the AI team generation engine. Used by cliq builder commands (generate, improve, gaps, capability) and by cliq server A2A builder capabilities (build_team, improve_role, validate_team).

Field	Type	Default	Description
`provider`	string	`"openai"`	LLM provider: `"openai"`, `"anthropic"`, or `"google"`
`api_key`	string	`""`	API key for the selected provider
`model`	string	Provider default	Model identifier. Defaults: `gpt-4o` (OpenAI), `claude-sonnet-4-20250514` (Anthropic), `gemini-2.0-flash` (Google)
`api_url`	string	Provider default	Override the API endpoint URL. Useful for proxies, Azure OpenAI, or local Ollama

OpenAI (default):

{
  "builder": {
    "provider": "openai",
    "api_key": "sk-...",
    "model": "gpt-4o"
  }
}

Anthropic (Claude):

{
  "builder": {
    "provider": "anthropic",
    "api_key": "sk-ant-...",
    "model": "claude-sonnet-4-20250514"
  }
}

Google (Gemini):

{
  "builder": {
    "provider": "google",
    "api_key": "AIza...",
    "model": "gemini-2.0-flash"
  }
}

Any OpenAI-compatible API can also be used with "provider": "openai" and a custom api_url — this works with Azure OpenAI, Ollama, vLLM, and LiteLLM proxies.

{
  "builder": {
    "provider": "openai",
    "api_key": "ollama",
    "model": "llama3.1:70b",
    "api_url": "http://localhost:11434/v1/chat/completions"
  }
}

docker

Container isolation settings. When enabled, pipelines run inside Docker containers instead of directly on the host. See Docker Container Isolation for the full guide.

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable container isolation
`image`	string	`"ghcr.io/elanamir/cliq-runner:latest"`	Docker image to use
`memory`	string	`"4g"`	Container memory limit
`cpus`	string	`"2"`	CPU limit
`network_mode`	string	`"bridge"`	Docker network mode (`bridge`, `host`, `none`)
`read_only_rootfs`	boolean	`true`	Read-only root filesystem for security
`max_containers`	number	`4`	Maximum concurrent containers
`extra_hosts`	string[]	`[]`	Extra `/etc/hosts` entries (e.g., `["myhost:10.0.0.1"]`)
`env`	Record<string, string>	`{}`	Docker-specific environment variables passed to the container

{
  "docker": {
    "enabled": true,
    "image": "ghcr.io/elanamir/cliq-runner:latest",
    "memory": "8g",
    "cpus": "4",
    "network_mode": "bridge",
    "read_only_rootfs": true,
    "max_containers": 2,
    "extra_hosts": ["registry.internal:10.0.0.5"],
    "env": {
      "NODE_ENV": "production"
    }
  }
}

database

Storage backend configuration. By default, cliq uses SQLite (zero config). Set url to a PostgreSQL connection string for multi-replica server deployments.

Field	Type	Default	Description
`url`	string	`""`	Connection string. Empty = SQLite. Set to a PostgreSQL URL for shared state

{
  "database": {
    "url": "postgres://cliq:[email protected]:5432/cliq"
  }
}

PostgreSQL is required when kubernetes.enabled is true. See Kubernetes Deployment for details.

kubernetes

Kubernetes Job-based pipeline execution. When enabled, pipelines run as K8s Jobs instead of local processes or Docker containers.

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable K8s Job execution
`namespace`	string	`"cliq"`	Namespace for pipeline Jobs
`workspace_pvc`	string	`"cliq-workspaces"`	ReadWriteMany PVC for shared workspaces
`config_configmap`	string	`"cliq-config"`	ConfigMap with settings and team configs
`api_key_secret`	string	`"cliq-secrets"`	Secret containing the Cursor API key
`api_key_secret_key`	string	`"cursor-api-key"`	Key within the Secret
`service_account`	string	`"cliq-runner"`	ServiceAccount for Job pods
`node_selector`	Record<string, string>	`{}`	Node selection constraints (e.g., `{"gpu": "true"}`)
`tolerations`	array	`[]`	Toleration rules for scheduling (see below)
`ttl_after_finished`	number	`300`	Seconds before completed Jobs are garbage collected

kubernetes.tolerations[]

Each toleration is a standard Kubernetes toleration object:

Field	Type	Description
`key`	string	Taint key to match
`operator`	string	`"Equal"` or `"Exists"`
`value`	string	Taint value to match (when operator is `"Equal"`)
`effect`	string	`"NoSchedule"`, `"PreferNoSchedule"`, or `"NoExecute"`

{
  "kubernetes": {
    "enabled": true,
    "namespace": "cliq",
    "workspace_pvc": "cliq-workspaces",
    "config_configmap": "cliq-config",
    "api_key_secret": "cliq-secrets",
    "api_key_secret_key": "cursor-api-key",
    "service_account": "cliq-runner",
    "node_selector": {
      "workload": "cliq"
    },
    "tolerations": [
      {
        "key": "dedicated",
        "operator": "Equal",
        "value": "cliq",
        "effect": "NoSchedule"
      }
    ],
    "ttl_after_finished": 600
  }
}

Requires database.url to be set to a PostgreSQL connection string. See Kubernetes Deployment for the full guide.

strict_input_validation

Field	Type	Default	Description
`strict_input_validation`	boolean	`false`	When `true`, unknown inputs are rejected even in headless/A2A mode

Controls whether the input resolver rejects inputs that are not declared by the team.

In interactive mode (terminal), unknown inputs are always rejected regardless of this setting — this catches typos in --input flags.

In headless/A2A mode, the behavior depends on this setting:

false (default) — unknown inputs are silently dropped. This is the correct behavior for external callers like the Jira plugin, which send ticket metadata (ticket_id, ticket_url, etc.) that teams may or may not declare as inputs.
true — unknown inputs are rejected with an error. Use this for locked-down production deployments where you want to ensure callers only send inputs the team explicitly expects.

Since this is a standard settings key, it follows the normal merge chain (global → project → workspace override). You can keep it lenient globally and lock it down per-project:

{
  "strict_input_validation": true
}

agents.hug — Human Gate

Human Gate (HUG) settings are configured under agents.hug. This includes server connection, reviewer routing, and chat settings for human-in-the-loop approval gates.

Field	Type	Default	Description
`server_url`	string	—	URL of the hug server. Required when using human gates — `cliq assemble` throws a hard error if missing
`token`	string	—	User JWT for hug server authentication. Managed automatically by `cliq hub login`
`enable_chat`	boolean	`false`	Enable the chat panel on the review page
`enable_dynamic_review_ui`	boolean	`false`	Reserved for future use
`max_artifact_size`	number	`50000`	Per-artifact character cap for LLM context
`max_total_artifact_size`	number	`200000`	Total artifact character cap for LLM context

agents.hug.reviewers[]

Named reviewer individuals and groups. Each entry has either channels (individual) or members (group) — not both.

Field	Type	Default	Description
`name`	string	—	Unique name, referenced in `team.yml` or in group `members`
`channels`	string[]	—	Notification routes for an individual (e.g., `"slack"`, `"slack:name"`, `"url:https://..."`)
`members`	string[]	—	Names of individuals or groups that belong to this group
`policy`	string	`"any"`	Approval policy (groups only). Only `"any"` is supported (first to submit decides)

agents.hug.llm

LLM provider configuration for the review page chat assistant. Required when enable_chat is true.

Field	Type	Default	Description
`provider`	string	—	LLM provider: `"anthropic"`, `"openai"`, or `"google"`
`model`	string	Provider default	Model name (e.g., `"claude-haiku"`, `"gpt-4o-mini"`, `"gemini-2.0-flash"`)
`api_key`	string	—	API key override. Falls back to the provider’s env var when omitted

{
  "agents": {
    "hug": {
      "server_url": "https://hug.example.com",
      "token": "hug-auth-token",
      "enable_chat": true,
      "llm": {
        "provider": "anthropic"
      },
      "reviewers": [
        { "name": "alice", "channels": ["slack:alice", "email:[email protected]"] },
        { "name": "bob", "channels": ["slack:bob"] },
        { "name": "carol", "channels": ["slack:carol"] },
        { "name": "architects", "members": ["alice", "bob"], "policy": "any" },
        { "name": "security", "members": ["carol"], "policy": "any" }
      ]
    }
  }
}

Each reviewer entry has either channels (individual) or members (group) — not both. Individuals define notification routes; groups compose individuals or other groups under a policy. With policy: "any" (the only policy supported today), all members are notified and the first person to submit a verdict decides.

channels is an array of strings. Use colon notation for named channels: "slack" (default webhook) or "slack:elan" (from agents.slack.channels). Use "url:https://..." for ad hoc webhook URLs.

See Human Gate (HUG) for an overview, or jump directly to Configuring Gates or Settings & Troubleshooting.

Verifying Integrations

Verify all configured agents at once:

cliq doctor                   # full environment check (includes agent validation)
cliq doctor agent             # validates all agents in the project
cliq doctor agent git         # checks git binary + token + repo access
cliq doctor agent slack       # sends a test message to the webhook
cliq doctor agent email       # verifies SMTP connection + auth

Best Practices

Use cliq settings instead of editing JSON — type-safe, validates keys and values, masks secrets
Put credentials in global settings (~/.cliqrc/settings.json) — tokens, API keys, email addresses
Use agents.<name>.<key> for agent settings — scoped per agent, validated by cliq doctor
Put project overrides in project settings (.cliq/settings.json) — base_branch, notification channels
Don’t duplicate credentials in project settings — they’re inherited from global automatically
Don’t commit settings files — both are gitignored by default
Run cliq doctor after configuring — catches auth issues before they surface mid-pipeline
Use "auto" for workflow streaming — zero overhead locally, auto-activates for server/A2A