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

Both project files (settings.json and resolved_settings.json) are gitignored.

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

  integrations    External service credentials and configuration.
  notifications   Event-driven notification routing to channels.
  id_prefix       Default prefix for instance IDs generated by cliq init.
  headless        Run orchestrator in foreground instead of tmux.
  hub             CliqHub team registry URL and token.
  logging         Structured server logging configuration.
  agents          Agent configuration — default agent and custom definitions.
  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.
  push            Global push security settings.
  hug             Human Gate server connection and reviewer routing.

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

Drill into any section to see its fields:

cliq settings integrations.github --info

integrations.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")
  branch_prefix   Prefix for feature branches (string, default: "cliq/")
  finalize_to     Automation boundary: "commit", "push", or "pr" (string, default: "pr")
  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 integrations.github.<keyname> --info' for additional info on <keyname>.

Go one level deeper for full detail on a single field — type, default, description, and example CLI commands:

cliq settings integrations.github.finalize_to --info

Read settings

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

cliq settings integrations.github.base_branch
# → main

cliq settings agents.default
# → cursor

Read an entire section to see all its values:

cliq settings integrations.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 integrations.github.base_branch develop

Set a value at the global level:

cliq settings integrations.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 integrations.github.token --stdin --global

Read a masked value:

cliq settings integrations.github.token --global
# → ghp_x****

Reveal the full value:

cliq settings integrations.github.token --global --unmask
# → ghp_xxxxxxxxxxxx

Work with arrays

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

cliq settings --add integrations.github.pr_labels needs-review
cliq settings --remove integrations.github.pr_labels auto
cliq settings --add push.allowed_modes replace --global

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 integrations.github.pr_draft

A typical setup session

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

# Set your default agent
cliq settings agents.default claude-code --global

# Configure GitHub integration
echo $GITHUB_TOKEN | cliq settings integrations.github.token --stdin --global
cliq settings integrations.github.base_branch main --global
cliq settings integrations.github.finalize_to pr --global

# Configure Slack notifications
echo $SLACK_WEBHOOK | cliq settings integrations.slack.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 test all

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

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

See cliq settings CLI Reference for the complete option reference.

---

How Settings Merging Works

When cliq run starts, it deep-merges global and project settings into .cliq/resolved_settings.json. This is the file agents and tools read at runtime.

• 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):

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

Project (.cliq/settings.json):

{
  "integrations": {
    "github": { "base_branch": "develop" }
  }
}

Resolved (.cliq/resolved_settings.json):

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

The token is inherited from global; base_branch is overridden by project.

---

Quick Reference

Section	Description
integrations	Jira, GitHub, Bitbucket, and Slack credentials and configuration
notifications	Event-driven notification routing to channels
id_prefix	Default prefix for instance IDs generated by cliq init
headless	Run orchestrator in foreground instead of tmux
hub	CliqHub team registry URL and token
logging	Structured server logging levels, rotation, and directory
agents	Agent configuration — default agent and custom agent definitions
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
push	Global push security settings — allowed modes
hug	Human Gate (HUG) server connection and reviewer routing
integrations.google	Google credentials for pull/push (service account or OAuth2)
integrations.microsoft	Microsoft Azure AD credentials for SharePoint/OneDrive

---

Complete Settings Example

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

{
  "integrations": {
    "jira": {
      "base_url": "https://your-org.atlassian.net",
      "email": "[email protected]",
      "api_token": "ATATT3x..."
    },
    "github": {
      "base_branch": "main",
      "remote": "origin",
      "branch_prefix": "cliq/",
      "finalize_to": "pr",
      "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"
    },
    "slack": {
      "webhook_url": "https://hooks.slack.com/services/T.../B.../xxx"
    },
    "google": {
      "credentials_file": "/path/to/service-account.json",
      "auth_mode": "service_account"
    },
    "microsoft": {
      "tenant_id": "your-azure-tenant-id",
      "client_id": "your-client-id",
      "client_secret": "your-client-secret"
    }
  },
  "notifications": {
    "on_start":          { "channels": ["slack"] },
    "on_phase_start":    { "channels": [] },
    "on_phase_complete": { "channels": [] },
    "on_complete":       { "channels": ["slack", "jira"] },
    "on_escalate": {
      "channels": ["slack", "jira"],
      "jira": { "transition_to": "Blocked" }
    },
    "on_cancel":         { "channels": ["slack"] },
    "on_pull":           { "channels": ["slack"] },
    "on_push":           { "channels": ["slack"] }
  },
  "id_prefix": "myproject",
  "headless": false,
  "hub": {
    "registry_url": "https://cliqhub.io",
    "token": ""
  },
  "logging": {
    "server_level": "info",
    "core_level": "info",
    "component_levels": {},
    "dir": "",
    "max_file_size_mb": 50,
    "max_files": 5
  },
  "agents": {
    "default": "cursor",
    "env": {
      "CURSOR_API_KEY": "key_abc123..."
    },
    "custom": {
      "qa-agent": {
        "entry": "agents/qa/index.js",
        "env": ["QA_MODE=strict"]
      }
    }
  },
  "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
  },
  "push": {
    "allowed_modes": ["create", "append", "replace"]
  }
}

---

Integrations

External service credentials and configuration. Each sub-key corresponds to an integration provider. For step-by-step setup, credential creation, and verification for every provider, see the Integrations page.

integrations.github

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
branch_prefix	string	"cliq/"	Prefix for feature branches
finalize_to	string	"pr"	Automation boundary: "commit", "push", or "pr"
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 Integrations — GitHub for setup.

---

integrations.bitbucket

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 Integrations — Bitbucket for setup.

---

integrations.jira

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

See Integrations — Jira for setup.

---

integrations.slack

Field	Type	Default	Description
webhook_url	string	""	Default Slack Incoming Webhook URL
channels	object	{}	Named channels with individual webhook URLs

The top-level webhook_url is the default channel. Named channels allow routing notifications to different Slack destinations:

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

Reference channels using dot notation:

• "slack" — uses the default webhook_url
• "slack:elan" — uses channels.elan.webhook_url
• "slack:incidents" — uses channels.incidents.webhook_url

This dot notation works in notification configs, hug reviewer channels, and anywhere a channel reference is accepted.

See Integrations — Slack for setup.

---

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
on_pull	External content is pulled into the workspace
on_push	A file is pushed to an external destination

Each event accepts a NotificationEventConfig object:

Field	Type	Default	Description
channels	string[]	[]	Channel references to notify (e.g., ["slack", "slack:incidents", "jira"])
slack.webhook_url	string	—	Override the global Slack webhook for this event
jira.transition_to	string	—	Jira status transition to apply (e.g., "Blocked", "Done")

{
  "notifications": {
    "on_start": {
      "channels": ["slack"]
    },
    "on_complete": {
      "channels": ["slack", "jira"],
      "jira": { "transition_to": "Done" }
    },
    "on_escalate": {
      "channels": ["slack", "jira"],
      "slack": { "webhook_url": "https://hooks.slack.com/services/T.../B.../escalation-channel" },
      "jira": { "transition_to": "Blocked" }
    },
    "on_cancel": {
      "channels": ["slack"]
    }
  }
}

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

---

id_prefix

Field	Type	Default	Description
id_prefix	string	""	Default prefix for instance IDs generated by cliq init

When set, cliq init generates IDs like myproject-a1b2c3 instead of a random ID. CLI flags --id and --id-prefix take precedence over this setting.

{
  "id_prefix": "myproject"
}

---

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 token for publishing. Generate with cliq hub login followed by cliq hub token

Browsing, searching, and installing are anonymous — no token required. A token is only needed for publishing teams.

In a future release, tokens will be stored keyed by registry URL in hub.tokens (a map of URL → token). The current hub.token field is retained for backward compatibility with single-registry setups.

{
  "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

Controls which agent runs each phase. See Cliq SDK for the full guide on built-in agents, choosing an agent, and building custom agents.

Field	Type	Default	Description
default	string	"cursor"	Default agent for phases that don’t specify an agent key. Built-in agents: cursor, claude-code, gemini, codex, hug
custom	Record<string, AgentConfig>	{}	User-defined agent configurations, keyed by name
env	Record<string, string>	{}	Environment variables injected into every agent process — local tmux panes and Docker containers. Docker’s docker.env values take precedence on collision

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

Environment Variables

Use agents.env to set environment variables that every agent needs, regardless of execution context:

{
    "agents": {
        "default": "cursor",
        "env": {
            "CURSOR_API_KEY": "key_abc123..."
        }
    }
}

These variables are exported before agent processes launch in tmux panes. For Docker containers, agents.env is merged with docker.env — if both define the same key, docker.env wins. This lets you set shared variables once and override them per-context when needed.

Custom Agent Config

Custom agents are built with the Cliq SDK (@cliqhub/cliq-sdk). Each entry has a uniform shape:

Field	Type	Required	Description
entry	string	yes	Path to the agent entry point script
env	string[]	no	Environment variable names the agent requires

{
    "agents": {
        "default": "cursor",
        "custom": {
            "qa-agent": {
                "entry": "agents/qa/index.js",
                "env": ["QA_STRICT=1"]
            }
        }
    }
}

---

server

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

Field	Type	Default	Description
port	number	4100	HTTP port for the cliq server. Overridden by --port CLI flag

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. Merged on top of agents.env — values here override agents.env on collision

{
  "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.

---

integrations.google

Field	Type	Default	Description
auth_mode	"service_account" | "oauth"	"service_account"	Authentication method
credentials_file	string	""	Path to a Google service account JSON key file
oauth_client_file	string	""	Path to an OAuth2 client secrets JSON file

See Integrations — Google for setup.

---

integrations.microsoft

Field	Type	Default	Description
tenant_id	string	""	Azure AD tenant ID
client_id	string	""	Azure AD application (client) ID
client_secret	string	""	Azure AD client secret

See Integrations — Microsoft for setup.

---

push

Global push security settings. These apply to ALL push operations from any team.

Field	Type	Default	Description
allowed_modes	string[]	["create", "append", "replace"]	Which push modes are permitted. Teams cannot use modes not in this list

Restrict to ["create"] to prevent teams from modifying existing documents:

{
  "push": {
    "allowed_modes": ["create"]
  }
}

See Pull & Push — Security for the full push security model.

---

hug

Human Gate (HUG) settings — configures the hug server connection, reviewer routing, and chat for human-in-the-loop approval gates. The hug section is not present in the default settings template — add it only when your team uses human 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	—	Bearer token for hug server API authentication
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

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)

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

{
  "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. Groups are a configuration convenience for organizing channels — define a person’s channels once, reference them from any number of groups.

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

When review.reviewer in team.yml references a name, the hug agent sends a concise Slack notification with the team name, instance ID, timeout, and a direct review link. If remind_every is set, reminders re-fire at the configured interval.

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

---

Verifying Integrations

See Integrations — Verify All for details. Quick reference:

cliq doctor test all          # tests all configured integrations
cliq doctor test github       # checks token + repo access
cliq doctor test bitbucket    # checks token + workspace/repo access
cliq doctor test slack        # sends a test message to the webhook
cliq doctor test jira         # authenticates; add --ticket KEY to verify project access
cliq doctor test google       # checks credentials + token exchange
cliq doctor test microsoft    # checks Azure AD credentials + token exchange

---

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
• Put project overrides in project settings (.cliq/settings.json) — base_branch, finalize_to, notification channels, id_prefix
• 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 test all after configuring — catches auth issues before they surface mid-pipeline
• Keep agents.custom in project settings — agent configurations often vary per project
• Use "auto" for workflow streaming — zero overhead locally, auto-activates for server/A2A