CLI Reference

Complete reference for every cliq command, organized by category.

Quick Start

Install cliq and run first-time setup:

curl -fsSL https://getcliq.io/cliq/install | bash -s -- --key cliqhub-early-2026
cliq setup

Check the installed version:

cliq --version

Display help for any command:

cliq --help
cliq <command> --help
cliq <command> <subcommand> --help

Command Summary

Global

Command	Description
`cliq setup`	One-time global setup — creates `~/.cliqrc/` and default settings
`cliq settings`	Read, write, and inspect configuration

Project

Command	Description
`cliq init`	Initialize `.cliq/` directory in the current project
`cliq assemble`	Deploy a team to the current project
`cliq req`	Resolve requirements and generate prompts, channels, and task board
`cliq run`	Launch all agents in a tmux session
`cliq status`	Display pipeline progress
`cliq doctor`	Check environment and integrations
`cliq doctor agent`	Validate agent configuration
`cliq auth google`	Manage Google OAuth2 authentication
`cliq clean`	Remove all cliq artifacts from the project
`cliq migrate`	Migrate a team.yml from old taxonomy to the new schema

Builder

Command	Description
`cliq builder generate`	Generate a complete team from a natural language description
`cliq builder improve`	Improve a single role using the LLM
`cliq builder gaps`	Analyse a team for gaps and suggest improvements
`cliq builder capability`	Generate or regenerate A2A metadata (tags, use_when, not_for)

Hub

Command	Description
`cliq hub login`	Authenticate with a registry
`cliq hub logout`	Clear hub and HUG credentials
`cliq hub token`	Create an API token

Team Management

Command	Description
`cliq team new`	Create a new empty team
`cliq team install`	Install a team from a local path or hub:// registry
`cliq team update`	Update installed teams to latest versions
`cliq team uninstall`	Remove an installed team
`cliq team publish`	Publish a team from a local path to a registry
`cliq team copy`	Copy a team to a local directory
`cliq team add-role`	Add a role to a team
`cliq team remove-role`	Remove a role from a team
`cliq team gen-workflow`	Generate workflow from roles, or import from a file
`cliq team edit-workflow`	Open team.yml in your editor
`cliq team validate`	Validate a team definition
`cliq team version`	Bump the team’s semantic version
`cliq team list`	List installed teams with versions and source
`cliq team info`	Show detailed team information (local or hub://)

Instance

Command	Description
`cliq instance list`	List all active cliq tmux sessions
`cliq instance info`	Show detailed status of an instance
`cliq instance attach`	Attach to a cliq tmux session
`cliq instance kill`	Kill a cliq tmux session

Server

Command	Description
`cliq server start`	Start the local cliq server
`cliq server stop`	Stop the running cliq server
`cliq server status`	Show cliq server status
`cliq server token generate`	Generate a random bearer token (offline)
`cliq server token hash`	Print the SHA-256 hash of a token (offline)
`cliq server token create`	Create a new bearer token
`cliq server token list`	List all bearer tokens
`cliq server token revoke`	Revoke a bearer token

Tool

Command	Description
`cliq tool run`	Run a tool by name
`cliq tool list`	List all available tools

Global Commands

cliq setup

Interactive setup wizard. Walks you through configuring your cliq environment: prerequisites, default agent, integrations, and credentials. Creates ~/.cliqrc/ with settings and an empty local team registry (teams/@local/) on first run.

Re-runnable — on subsequent runs, shows current values as defaults. Press Enter to keep them, or type a new value to change.

cliq setup [options]

Option	Description
`--import <path>`	Import a `settings.json` file (skips the wizard)
`--reset`	Wipe `~/.cliqrc/` and start fresh (prompts for confirmation)
`--force`	Skip confirmations (use with `--reset` or `--import`)
`--non-interactive`	Accept all defaults without prompting (for CI/scripting)

The wizard covers:

Prerequisites — checks for Node.js and tmux
Import — optionally load settings from another machine
Default agent — choose cursor, claude-code, gemini, or codex, and set the API key
Instance ID prefix — optional prefix for tmux session names
CliqHub — log in to browse, install, and publish teams
Source control — GitHub or Bitbucket integration for branches and PRs
Jira — issue tracking and gate escalation
Slack — pipeline notifications via webhook channel
Google — Drive, Docs, and Sheets access
Microsoft — SharePoint and OneDrive access
AI Team Builder — LLM provider for AI-assisted team creation
Diagnostics — verifies the resulting configuration

cliq setup                                      # Interactive wizard
cliq setup --import ~/team-config/settings.json  # Import settings
cliq setup --reset                               # Factory reset
cliq setup --non-interactive                     # Bootstrap with defaults

cliq settings

Read, write, and inspect configuration with git config-like semantics. Supports two scopes (global and project), dot-notation keys, schema-based type coercion, array operations, and secret masking.

cliq settings [key] [value] [options]

When called with no key, lists all settings. When called with a key that maps to an object, lists all keys under that section. When called with a leaf key, prints the value (or (not set) with exit code 1 if valid but unconfigured). Unknown keys produce an error with a contextual --info hint pointing to the deepest valid section. When called with a key and value, writes the value.

Option	Description
`--global`	Target global settings (`~/.cliqrc/settings.json`)
`--project`	Target project settings (`.cliq/settings.json`)
`--unset <key>`	Remove a key from the target file
`--add <key>`	Append a value to an array field
`--remove <key>`	Remove a value from an array field
`--stdin`	Read the value from stdin instead of the command line
`--unmask`	Show unmasked secret values (tokens, API keys)
`--info`	Show documentation for a setting or section. Non-leaf results include a navigation hint.

Scope and Precedence

Without --global or --project, reads show the merged (resolved) view — project values override global. Writes default to the project scope; if not inside a project, they fall back to global.

Flag	Reads from	Writes to
(none, inside project)	merged (global + project)	`.cliq/settings.json`
(none, outside project)	`~/.cliqrc/settings.json`	`~/.cliqrc/settings.json`
`--global`	`~/.cliqrc/settings.json`	`~/.cliqrc/settings.json`
`--project`	`.cliq/settings.json`	`.cliq/settings.json`

Type Coercion

Values are coerced based on the schema derived from the settings template:

Boolean fields accept true or false (case-insensitive).
Number fields must parse to a valid number.
Enum fields must match one of the allowed values (e.g., logging.server_level accepts error, warn, info, debug, trace).
Array fields cannot be set directly — use --add and --remove.
Object keys cannot be set directly — set leaf keys instead.

Secret Masking

Fields that hold credentials (tokens, API keys) are masked by default — only the first 4 characters are shown, followed by ****. This applies to both simple leaf fields and secret fields inside array elements (e.g., client_secret within mesh entries). Use --unmask to reveal full values.

Examples

# Read a value
cliq settings agents.git.github.base_branch

# Write a string
cliq settings agents.git.github.base_branch develop

# Write at global scope
cliq settings agents.git.github.base_branch develop --global

# Write a secret from stdin
echo $TOKEN | cliq settings hub.token --stdin --global

# List all resolved settings
cliq settings

# List global settings only
cliq settings --global

# Read an entire section
cliq settings agents.git.github

# Array: append
cliq settings --add agents.git.github.pr_labels deploy --global

# Array: remove
cliq settings --remove agents.git.github.pr_labels auto

# Unset a key
cliq settings --unset agents.git.github.pr_draft

# Show a secret unmasked
cliq settings hub.token --unmask --global

# Show documentation for all sections
cliq settings --info

# Show documentation for a section
cliq settings agents.git.github --info

# --- Slack channel setup ---
cliq settings agents.slack.channels.default.webhook_url "https://hooks.slack.com/services/T.../B.../..." --global

# --- Email (SMTP) setup ---
cliq settings agents.email.smtp_host smtp.example.com --global
cliq settings agents.email.smtp_port 587 --global
cliq settings agents.email.from_address [email protected] --global
echo "$SMTP_PASS" | cliq settings agents.email.password --stdin --global
cliq settings --add agents.email.channels.default [email protected] --global
cliq settings --add agents.email.channels.ops [email protected] --global

# --- Wire channels to events ---
cliq settings --add notifications.on_complete.channels email
cliq settings --add notifications.on_escalate.channels email:ops

# Read a valid but unconfigured key — prints "(not set)", exit code 1
cliq settings agents.git.github.token

# Unknown key — error with contextual hint
# error: Unknown key 'agents.jira.badkey'.
#   Run 'cliq settings agents.jira --info' to navigate the agents.jira schema.
cliq settings agents.jira.badkey

Project Commands

cliq init

Initialize the .cliq/ directory structure in the current project. Creates directories, settings, and .gitignore entries. Does not create an instance ID — that happens at cliq run time.

cliq init [options]

Option	Description
`--name <prefix>`	Set a project name used as the instance ID prefix during `cliq run`

The name is stored in .cliq/project.name and persists across runs. When set, instance IDs look like my-api-a1b2c3 instead of cliq-a1b2c3.

cliq init
cliq init --name my-api

Multi-repo workspaces

For projects spanning multiple repositories, create a workspace directory, clone the repos into it, then initialize:

mkdir my-workspace && cd my-workspace
git clone https://github.com/org/api.git
git clone https://github.com/org/frontend.git
cliq init
cliq assemble feature-dev-js
cliq req requirements.md
cliq run

Cliq auto-detects child git repos. Phases with scope: repo commands run once per repo. Git operations (branch, commit, push, PR) are applied to each repo independently.

cliq assemble

Deploy a team from the registry into the current project. Creates .cliq/roles/, workflow.yml, and the channel structure. Run from a project directory (or multi-repo workspace root) that has been initialized with cliq init.

cliq assemble <team> [options]

Argument	Description
`team`	Team name or scoped reference

Option	Description
`--dir <path>`	Resolve team from a local directory instead of the install directory

Accepts scoped references (@cliq/feature-dev-js) or bare names (feature-dev-js). Bare names are resolved in order: @local → other @* scopes.

During assembly, cliq generates an agents.json manifest and warns about custom agents that need user configuration:

⚠ Agent 'custom-agent' has no entry point — configure it in settings.json under agents before running

See Cliq SDK for details on agents and assembly.

cliq assemble feature-dev-js
cliq assemble @cliq/feature-dev-js
cliq assemble my-team --dir ./teams/my-team

cliq req

Resolve requirements and generate prompts, channels, and the task board.

cliq req [options]

Option	Description
`-s, --source <ref>`	Source for requirements — file path, URL, or URI scheme (e.g. `jira:KEY`)
`-m, --message <text>`	Use an inline string as the requirement
`--stdin`	Read requirement text from stdin
`--nospec`	Start workflow with default requirements (no spec needed)
`--no-docker`	Run without Docker
`-i, --input <key=value...>`	Provide team input values (repeatable)

Only one input source is allowed per invocation: -s, -m, --stdin, or --nospec.

Source resolution: The -s flag accepts file paths, full URLs, and URI schemes. The scheme determines how the source is resolved:

Source	Resolution
`-s requirements.md`	Local file
`-s https://example.com/spec.md`	HTTP fetch
`-s jira:PROJ-123`	Jira ticket (requires `agents.jira` in settings)
`-s jira:PROJ-1,PROJ-2`	Multiple Jira tickets

Bare paths (no scheme) are treated as local files.

Validation gate: Before executing, cliq req checks that all prerequisites are met — a requirement spec and any inputs defined by the team. If anything is missing, it prints exactly what’s needed and a copy-paste example command, then exits without touching project state. This applies whether you omit the spec entirely or provide a spec but forget an --input flag.

Input resolution: Team inputs are resolved exclusively from --input flags (or interactive prompts in non-headless mode). They are not parsed from the requirement text.

# Check what the team needs (no spec, shows what's missing)
cliq req

# Provide everything — runs the pipeline
cliq req -s requirements.md
cliq req -s requirements.md --input company=acme --input year=2026
cliq req -s https://example.com/spec.md
cliq req -s requirements.md --input ticket=PROJ-123
cliq req -m "Build a REST API with JWT auth and role-based access control"
echo "Build a hello world app" | cliq req --stdin
cat spec.txt | cliq req --stdin
cliq req --nospec
cliq req -s requirements.md --no-docker

cliq run

Launch all agents in a tmux session and run the pipeline.

cliq run [options]

Option	Description
`-f, --force`	Skip confirmation when re-running after a failed pipeline
`-H, --headless`	Run orchestrator in foreground, agents in background tmux
`-a, --agent <name>`	Override the default agent (e.g. `claude-code`, `gemini`)
`--debug`	Enable debug-level logging for this run
`--docker`	Run pipeline inside a Docker container
`--no-docker`	Force local executor (bypass `docker.enabled` and `kubernetes.enabled`)
`--dashboard`	With `--docker`: require server, suppress terminal streaming
`--settings <path>`	Additional settings file applied with highest precedence for this run only

Pre-flight checks: Before launching, cliq run verifies that all prerequisite steps have been completed — project initialized, team assembled, requirements set, and prompts generated. If the team defines inputs, cliq run also checks that inputs.json contains all required values. If any are missing, it fails with a message to re-run cliq req with the appropriate --input flags.

When docker.enabled is true in settings, Docker is the default. When kubernetes.enabled is true, K8s takes precedence. --no-docker bypasses both. See Docker Container Isolation and Kubernetes Deployment. See Cliq SDK for -a/--agent details.

--settings <path> layers a JSON settings file on top of the global + project merge for this one run only. Nothing is persisted; the override applies uniformly to the orchestrator, every agent, and any container or sub-team launched by the run. See Per-Run Override for full semantics, precedence, and the audit log entry emitted at run start.

cliq run
cliq run -f
cliq run -H
cliq run --agent claude-code
cliq run --docker --dashboard
cliq run --no-docker
cliq run --settings ./prod.json

cliq status

Display pipeline progress, phase state, and verdicts.

cliq status [options]

Option	Description
`-v, --verbose`	Show detailed diagnostics (verdicts, timing, settings, logs)

cliq status
cliq status -v

cliq doctor

Full environment check — verifies local dependencies (Node.js, agent CLI, tmux, git), checks hug server connectivity (when configured), validates agent configurations, and optionally verifies a team’s tools.

cliq doctor [team_ref]

Argument	Description
`team_ref`	Team reference to check required tools (optional)

cliq doctor
cliq doctor @cliq/feature-dev-js

cliq doctor agent

Validate agent configuration — binary availability, required settings, and connectivity. Without a name, checks all agents in the current project manifest. With a name, checks that specific agent.

cliq doctor agent [name]

Argument	Description
`name`	Agent name to validate (optional — checks all agents if omitted)

cliq doctor agent                # validate all agents in the project
cliq doctor agent curl           # validate a specific agent
cliq doctor agent jira
cliq doctor agent slack          # validate Slack agent
cliq doctor agent email          # validate email agent

cliq auth google

Manage Google OAuth2 authentication. Default action runs the interactive browser-based authorization flow.

cliq auth google [options]

Option	Description
`--status`	Show current token status (stored, valid, expired)
`--revoke`	Revoke token with Google and clear local storage
`--client-file <path>`	Path to OAuth client secrets JSON (overrides settings)

cliq auth google                            # run the authorization flow
cliq auth google --client-file ~/client.json  # specify client file explicitly
cliq auth google --status                   # check token status
cliq auth google --revoke                   # revoke and clear

The client secrets file is resolved from (in order): --client-file flag, then agents.gdrive.oauth_client_file in settings.json. After authorization, the refresh token is stored at ~/.cliqrc/google_token.json with restrictive permissions (0600).

See Google Drive Agent for the full OAuth setup guide.

cliq clean

Remove all cliq artifacts from the project (.cliq/ and generated config files).

cliq clean [options]

Option	Description
`-f, --force`	Skip confirmation prompt

cliq clean
cliq clean -f

cliq migrate

Migrate a team.yml from the old taxonomy (hug/exec/pull/push phase types) to the current schema. Useful when upgrading teams created with earlier versions of cliq.

cliq migrate [path] [options]

Option	Description
`--dry-run`	Show what would change without writing

cliq migrate                          # migrate team.yml in the current directory
cliq migrate path/to/team.yml         # migrate a specific file
cliq migrate --dry-run                # preview changes only

When run without --dry-run, the original file is backed up before overwriting.

Builder Commands

AI-powered team generation and refinement. All builder commands require a configured LLM provider in ~/.cliqrc/settings.json under the builder section. Every subcommand accepts --provider and --model flags to override the configured defaults for a single invocation.

cliq builder generate

Generate a complete team from a natural language description. Exactly one input source is required. Files are written directly into the target directory (current directory by default, or [path] if specified).

cliq builder generate -f <file> [path] [options]
cliq builder generate -m <text> [path] [options]
cliq builder generate --stdin [path] [options]

Input (exactly one required)	Description
`-f, --file <path>`	Read instructions from a file
`-m, --message <text>`	Use an inline string as the instructions
`--stdin`	Read instructions from stdin

Argument	Description
`path`	Write to a specific directory instead of cwd (optional, created if missing)

Option	Description
`--name <name>`	Override the LLM-generated team name (sets `name` in team.yml)
`--dry-run`	Show what would be created without writing files
`--force`	Overwrite if `team.yml` already exists in the target directory
`--provider <name>`	LLM provider override (`openai`, `anthropic`, `google`)
`--model <model>`	Model override (e.g. `gpt-4o`, `claude-sonnet-4-20250514`)

The generated team includes a team.yml with workflow phases, role files for each agent, and A2A metadata fields (tags, inputs, use_when, not_for). The team is validated before writing — if validation fails, errors are displayed and nothing is written.

If your description references installed teams via @scope/name (e.g. “use @acme/security-audit”), the builder composes them as type: team phases with correct $(dirs.*) path stitching. All referenced teams must be locally installed.

cliq builder generate -m "TDD pipeline for a Python FastAPI project"
cliq builder generate -m "CI pipeline using @acme/security-audit" --dry-run
cliq builder generate -f spec.txt --name my-custom-team ./my-team
cat spec.txt | cliq builder generate --stdin --dry-run

cliq builder improve

Improve a single role in an existing team using the LLM.

cliq builder improve <team> --role <role> [options]

Argument	Description
`team`	Team name or scoped reference

Option	Description
`--role <role>`	Role to improve (required)
`--dir <path>`	Resolve team from a local directory instead of the install directory
`--instruction <text>`	Specific improvement instruction (reads from stdin when set to `-`)
`--dry-run`	Preview the improved role without writing
`--provider <name>`	LLM provider override
`--model <model>`	Model override

Without --instruction, the LLM uses its own judgement to improve the role based on the team’s context. With an instruction, it targets a specific aspect.

cliq builder improve my-team --role architect
cliq builder improve my-team --role reviewer --instruction "add security review checklist"
cliq builder improve @local/my-team --role developer --dry-run
echo "focus on error handling" | cliq builder improve my-team --role developer --instruction -

cliq builder gaps

Analyse an existing team for gaps and suggest improvements — missing phases, workflow issues, or coverage holes.

cliq builder gaps <team> [options]

Argument	Description
`team`	Team name or scoped reference

Option	Description
`--provider <name>`	LLM provider override
`--model <model>`	Model override

Prints a numbered list of suggestions with type, title, description, and optionally a suggested phase or role.

cliq builder gaps my-team
cliq builder gaps @cliq/feature-dev-js

cliq builder capability

Generate or regenerate A2A metadata (tags, use_when, not_for) for an existing team. The metadata fields are written as top-level keys in team.yml and enable A2A discovery.

cliq builder capability <team> [options]

Argument	Description
`team`	Team name or scoped reference

Option	Description
`--dry-run`	Preview the A2A metadata without writing to `team.yml`
`--provider <name>`	LLM provider override
`--model <model>`	Model override

cliq builder capability my-team
cliq builder capability my-team --dry-run
cliq builder capability @local/my-team --provider anthropic --model claude-sonnet-4-20250514

Hub Commands

Authentication with CliqHub registries. All team operations (install, update, publish, info) are under Team Management Commands. Use the CliqHub web UI for browsing and searching teams.

Authenticate with a CliqHub registry. Prompts for username and password. On success, saves the JWT token to ~/.cliqrc/settings.json under hub.token. If the registry has a HUG server integrated, also provisions a HUG user JWT and writes hug.server_url and hug.token to settings.

cliq hub login [registry_url]

Argument	Description
`registry_url`	Registry URL (optional; defaults to `settings.hub.registry_url`)

cliq hub login
cliq hub login https://internal.corp/registry

cliq hub logout

Clear hub and HUG credentials from ~/.cliqrc/settings.json. Removes hub.token, hug.token, and hug.server_url. Other settings (like hub.registry_url and hug.reviewers) are preserved.

cliq hub logout

cliq hub logout

cliq hub token

Generate a named API token for headless/CI use. The token is shown once and must be saved — it cannot be retrieved again.

cliq hub token <name> [registry_url]

Argument	Description
`name`	Name for the token (for identification)
`registry_url`	Registry URL (optional; defaults to `settings.hub.registry_url`)

Requires cliq hub login first.

cliq hub token ci-publish
cliq hub token deploy-key https://internal.corp/registry

Team Management Commands

Commands for managing, inspecting, and manually assembling teams. For AI-powered team creation, see Builder Commands. For registry authentication, see Hub Commands.

Teams are stored in the registry at ~/.cliqrc/teams/. They can be referenced as bare names (feature-dev-js) or scoped (@cliq/feature-dev-js). Bare names go to @local/. Scoped names resolve to ~/.cliqrc/teams/@scope/.

cliq team new

Create a new empty team.

cliq team new <name> [path]

Argument	Description
`name`	Team name — bare (`my-team`) or scoped (`@myorg/my-team`)
`path`	Write to a specific directory instead of the resolved default (optional)

cliq team new my-pipeline
cliq team new @myorg/my-pipeline
cliq team new @myorg/my-pipeline ~/myorg-teams

cliq team install

Install a team from a local path or a hub:// registry URI.

cliq team install <source> [options]

Argument	Description
`source`	Local filesystem path or `hub://@scope/name[@version]`

Option	Description
`--force`	Reinstall even if the same version is already installed; skip all confirmation prompts

Local installs read team.yml from the path. Unscoped teams go to @local. Hub installs download from settings.hub.registry_url. Both write a .cliq-source provenance marker.

When installing over an existing team (same @scope/name already installed), the user must type the full team name to confirm the overwrite. Fresh installs (no existing team) proceed without prompts. Use --force to skip all prompts.

cliq team install ./my-team
cliq team install ./@acme/my-pipeline
cliq team install hub://@acme/my-pipeline
cliq team install hub://@acme/[email protected]
cliq team install ./my-team --force

cliq team update

Update installed teams to latest versions. Checks all installed teams that have a .cliq-source provenance marker. Hub-sourced teams are checked against the registry. Local-sourced teams are checked against their original path.

cliq team update [ref] [options]

Argument	Description
`ref`	Specific team to update (optional)

Option	Description
`-f, --force`	Skip confirmation prompt

cliq team update
cliq team update @acme/deploy
cliq team update --force

cliq team uninstall

Remove an installed team from ~/.cliqrc/teams/.

cliq team uninstall <ref>

Argument	Description
`ref`	Team to remove (`@scope/name`)

cliq team uninstall @acme/my-pipeline
cliq team uninstall @local/my-team

cliq team copy

Copy a team from the registry to a local directory. Optionally rewrite the team’s scope and name in team.yml.

cliq team copy <source> <dest> [scope]

Argument	Description
`source`	Source registry reference (e.g. `@cliq/feature-dev-js`)
`dest`	Local directory path (must not exist; will be created)
`scope`	Optional — rewrite `team.yml` name: `@acme` (scope only, keeps bare name) or `@acme/my-tdd` (full ref, changes both scope and name). If omitted, `team.yml` is left untouched.

cliq team copy @cliq/feature-dev-js ./my-tdd
cliq team copy @cliq/hello-world ./my-hello @myorg
cliq team copy @cliq/feature-dev-js ./my-tdd @myorg/my-tdd
cliq team copy @local/my-experiment ./my-experiment-v2

cliq team add-role

Add a role to a team.

cliq team add-role <team> <role> [options]

Argument	Description
`team`	Team to add the role to
`role`	Role name to add

Option	Description
`--from <path>`	If `--from` is provided, copies from the given file path. Otherwise creates a blank role file.

cliq team add-role my-pipeline reviewer
cliq team add-role my-pipeline my-reviewer --from ./templates/reviewer.md

cliq team remove-role

Remove a role from a team.

cliq team remove-role <team> <role>

Argument	Description
`team`	Team to remove the role from
`role`	Role to remove

cliq team remove-role my-pipeline reviewer

cliq team gen-workflow

Generate a sequential workflow from the team’s roles, or import a workflow from a file.

cliq team gen-workflow <team> [file] [options]

Argument	Description
`team`	Team to generate the workflow for
`file`	YAML file to import as the workflow (optional)

Option	Description
`--edit`	Open `team.yml` in editor after generating

If the team already has a workflow, you are prompted to confirm replacement.

cliq team gen-workflow my-pipeline
cliq team gen-workflow my-pipeline workflow.yml --edit

cliq team edit-workflow

Open a team’s team.yml in your editor.

cliq team edit-workflow <team>

Argument	Description
`team`	Team whose workflow to edit

Vendor teams (@cliq scope) cannot be edited directly — copy first with cliq team copy.

cliq team edit-workflow my-pipeline

cliq team validate

Validate a team definition for consistency. Accepts either an installed team ref or a path to a source directory — handy for checking a team you’re authoring before installing or publishing.

cliq team validate [ref-or-path]

Argument	Description
`ref-or-path`	Installed team ref (`@scope/name` or bare name), or a path (`.`, `./dir`, `../dir`, `/abs/dir`). Defaults to `.` (current directory).

The command checks the workflow + role files and warns about bare relative paths in role content (which won’t resolve correctly when the team is embedded as a sub-team). Warnings are advisory — the command exits 0 as long as base validation passes.

For hard-fail behavior before publishing (errors instead of warnings), use:

cliq team publish <path> --dry-run

cliq team validate                         # validate ./team.yml in cwd
cliq team validate ./hello-world           # validate a sibling source dir
cliq team validate @cliq/feature-dev-js    # validate an installed team

cliq team publish

Publish a team from a local path to a CliqHub registry. Reads name, scope, and version from team.yml. Rejects @local scope.

cliq team publish <path> [registry] [options]

Argument	Description
`path`	Local filesystem path to the team
`registry`	Target registry URL (optional; defaults to `settings.hub.registry_url`). Use `hub://` to be explicit about the default

Option	Description
`--access <level>`	Visibility: `public` (default), `private`, or `draft`
`-m, --message <text>`	Changelog message for this version
`--dry-run`	Validate and preview the publish without uploading
`--force`	Publish despite bare-relative-path lint warnings (use sparingly). Does not override structural validation failures (missing version, bad role files, etc.)

Requires cliq hub login first.

By default, publish blocks on bare-relative-path warnings — paths in role files that should be qualified with $(dirs.*) ($(dirs.project), $(dirs.self), or $(dirs.<phase>)) for portability when the team is embedded as a sub-team. Use --force only when you’ve confirmed the flagged token is a false positive (e.g. prose like bold/italic).

cliq team publish ./@myorg/tdd-pipeline
cliq team publish ./my-team --access private
cliq team publish ./@myorg/tdd-pipeline hub://
cliq team publish ./@myorg/tdd-pipeline https://other.registry
cliq team publish ./@myorg/tdd-pipeline -m "Added security audit phase"
cliq team publish ./@myorg/tdd-pipeline --dry-run
cliq team publish ./@myorg/tdd-pipeline --force

cliq team version

Bump the semantic version field in a team’s team.yml. This is a local file operation — it never touches the team registry under ~/.cliqrc/teams/. It operates on the directory at [path] (defaults to the current directory). Git actions are opt-in via --git-tag. See Versioning for details.

cliq team version <bump> [path] [options]

Argument	Description
`bump`	Bump type: `patch`, `minor`, or `major`
`path`	Directory containing the `team.yml` to bump (default: current directory)

Option	Description
`--git-tag`	Create a git commit + tag (`vX.Y.Z`) after bumping. Requires `path` to be inside a git work-tree.

If no version exists yet, any bump type produces 1.0.0.

cd ~/src/cliq-teams/@myorg/my-pipeline
cliq team version patch                              # 1.2.0 → 1.2.1
cliq team version minor                              # 1.2.0 → 1.3.0
cliq team version major                              # 1.2.0 → 2.0.0
cliq team version patch ../sibling-team              # operate on a sibling dir
cliq team version patch --git-tag                    # bump + git commit + tag

cliq team list

List installed teams with versions and source, grouped by scope. Each team’s team.yml is validated during listing — issues are surfaced inline with a ⚠ warning:

Unparseable YAML — the file could not be parsed.
Missing name — the name field is absent.
Bare name — the name is not in the required @scope/name format.
Name / directory mismatch — the name in team.yml does not match the directory structure.
Unscoped directory — the team directory is not inside a @scope/ parent.

cliq team list

Example output:

Teams:

  @cliq
    tdd
    tdd-git

  @local
    my-team
    broken-team  ⚠ team.yml missing "name" field

cliq team info

Show detailed team information. Use hub://@scope/name for registry info. Displays workflow DAG, phases, roles, external data, and A2A metadata. Emits a warning if the team.yml name does not match the directory-derived reference.

cliq team info <ref> [--brief]

Argument	Description
`ref`	Team to display (`@scope/name` or `hub://@scope/name`)

Option	Description
`--brief`	Compact one-line-per-field output

cliq team info @cliq/feature-dev-js
cliq team info @local/my-pipeline
cliq team info hub://@acme/deploy
cliq team info @cliq/feature-dev-js --brief

Instance Commands

Each cliq run generates an instance ID (using .cliq/project.name as a prefix if set) and creates a tmux session with that name. This enables multiple concurrent pipelines across different projects. When instance_id is omitted from commands below, it is read from .cliq/cliq.id in the current directory.

cliq instance list

List all active cliq tmux sessions across all projects.

cliq instance list [options]

Option	Description
`--all`	Include completed and failed instances (not just active)
`--tree`	Show instance hierarchy with sub-instances

Shows the instance ID for each active session.

cliq instance info

Show detailed status of a running or recent instance, including pipeline progress, active phase, and sub-instances.

cliq instance info [instance_id]

Argument	Description
`instance_id`	Instance to inspect (optional; defaults to current project)

cliq instance info
cliq instance info my-api-5f5c14

Example output:

Instance:    my-api-5f5c14
Project:     /Users/elan/src/my-api
Team:        @acme/feature-dev-js
Status:      RUNNING
Started:     2026-04-30 14:22:03 (2h 15m ago)
Session:     my-api-5f5c14 (tmux)

Pipeline:    architect → developer → security-audit → reviewer
Progress:    2/4 phases complete
Active:      security-audit

Sub-instances:
  └─ my-api-5f5c14.security-audit::cliq-a3f2c1  RUNNING  (phase: security-audit)

cliq instance attach

Attach to a cliq tmux session.

cliq instance attach [instance_id]

Argument	Description
`instance_id`	Instance to attach to (optional; defaults to current project)

cliq instance attach
cliq instance attach myproject-a1b2c3

cliq instance kill

Kill a cliq tmux session.

cliq instance kill [instance_id] [options]

Argument	Description
`instance_id`	Instance to kill (optional; defaults to current project)

Option	Description
`--no-cascade`	Kill only the top-level instance without killing sub-instances

cliq instance kill
cliq instance kill myproject-a1b2c3
cliq instance kill myproject-a1b2c3 --no-cascade

Server Commands

The local server provides an HTTP/WebSocket API for the Dashboard, A2A agent communication, and mesh networking.

cliq server start

Start the local cliq server.

cliq server start [options]

Option	Description
`-p, --port <port>`	Port number (default: `4100`)
`--a2a`	Enable A2A agent mode (join configured meshes)
`--mesh <names...>`	Activate specific mesh(es) by name (implies `--a2a`)
`--public-url <url>`	Public URL for agent card and mesh registration (e.g. ngrok tunnel; implies `--a2a`)

cliq server start
cliq server start -p 8080
cliq server start --a2a
cliq server start --mesh production staging
cliq server start --public-url https://abc123.ngrok.io

cliq server stop

Stop the running cliq server.

cliq server stop

cliq server status

Show server status including PID, port, and uptime.

cliq server status

cliq server token

Manage bearer tokens for server authentication. Tokens are stored as SHA-256 hashes in the database and survive server restarts. See Server — Authentication for an overview.

cliq server token generate

Generate a random cliq_sk_ bearer token and print it to stdout. This is an offline operation — no running server or database is required.

cliq server token generate

cliq server token generate
# → cliq_sk_a1b2c3d4e5f6...

Useful for pre-generating tokens to set as CLIQ_ADMIN_TOKEN or for manual database insertion.

cliq server token hash

Print the SHA-256 hash of a plaintext token. Offline — no server needed. Useful for manual database operations or verifying token hashes.

cliq server token hash <plaintext>

Argument	Description
`plaintext`	The `cliq_sk_` token to hash

cliq server token hash cliq_sk_a1b2c3d4e5f6...
# → 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

cliq server token create

Create a new bearer token and persist it in the database.

cliq server token create --label <label> [options]

Option	Description
`--label <label>`	Human-readable label for the token (required)
`--server <url>`	Server URL (defaults to local running server)
`--token <token>`	Auth token for the request (defaults to local session token)
`--db-url <url>`	Connect directly to the database — no running server needed

By default, create authenticates against the running local server using the session token from ~/.cliqrc/server.json. Use --server and --token to target a remote server. Use --db-url for headless provisioning without a running server.

# Local server (auto-discovers session token)
cliq server token create --label "jira-plugin"

# Remote server
cliq server token create --label "ci-agent" \
  --server https://cliq.prod.example.com \
  --token cliq_sk_admin...

# Direct database (no server needed)
cliq server token create --label "bootstrap" \
  --db-url postgresql://user:pass@db:5432/cliq

The plaintext token is shown once and cannot be retrieved again. Save it immediately.

cliq server token list

List all bearer tokens with their status.

cliq server token list [options]

Option	Description
`--server <url>`	Server URL (defaults to local running server)
`--token <token>`	Auth token (defaults to local session token)

cliq server token list

Example output:

ID          Label         Source  Created              Last Used            Active
----------------------------------------------------------------------------------------------
tok_a1b2c3  jira-plugin   api     2026-05-09 14:30:00  2026-05-09 15:12:33  yes
tok_d4e5f6  ci-agent      cli     2026-05-09 14:35:00  -                    REVOKED
tok_g7h8i9  admin         env     2026-05-09 14:00:00  2026-05-09 15:00:00  yes

cliq server token revoke

Revoke a bearer token by ID. Revoked tokens are immediately rejected on all subsequent requests.

cliq server token revoke <id> [options]

Argument	Description
`id`	Token ID to revoke (e.g. `tok_a1b2c3`)

Option	Description
`--server <url>`	Server URL (defaults to local running server)
`--token <token>`	Auth token (defaults to local session token)

cliq server token revoke tok_a1b2c3

Tool Commands

Built-in verification tools used by workflow checks and agents. Each tool exits with code 0 on success and 1 on failure.

cliq tool run

Run a built-in tool by name. Each tool exits with code 0 on success and 1 on failure.

cliq tool run <name>

Argument	Description
`name`	Tool name

cliq tool list

List all available tools with their descriptions.

cliq tool list

Exit Codes

Code	Meaning
`0`	Success
`1`	Failure — invalid arguments, command error, tool failure, or failed environment check

Commands that encounter errors set process.exitCode = 1. Uncaught exceptions and unhandled promise rejections also result in exit code 1.

Environment Variables

Variable	Description
`CLIQ_HOME`	Override the default cliq home directory (`~/.cliqrc`)
`CLIQ_ADMIN_TOKEN`	Bootstrap a bearer token into the database on server start (for containerized/headless deployments)
`EDITOR`	Editor opened by `team edit-workflow` and `--edit` flags