Installing & Using Teams

Install teams from CliqHub or from local paths with a single command. Assemble them into projects, run pipelines, keep everything up to date.

Quick walkthrough

The full consumer lifecycle — install, use, update — in one block:

# 1. Install from CliqHub
cliq team install hub://@cliq/feature-dev-js

# 2. Use in a project
cd ~/my-project
cliq init
cliq assemble @cliq/feature-dev-js
cliq req -s requirements.md
cliq run

# 3. Check what's installed
cliq team list

# 4. Check for updates
cliq team info hub://@cliq/feature-dev-js

# 5. Update
cliq team update

The rest of this page covers each step in detail.

Installing teams

From CliqHub

cliq team install hub://@cliq/feature-dev-js

The team is downloaded from the registry and extracted to ~/.cliqrc/teams/@cliq/feature-dev-js/. A .cliq-source provenance marker is written recording the source as hub.

From a local path

cliq team install ./my-team
cliq team install ./@acme/my-pipeline

The team is copied from the local directory. The name in team.yml determines the installed scope and name. If the name is unscoped, it goes to @local/. A .cliq-source provenance marker records the source as local with the original path.

Version pinning

Install a specific version from the hub with @version syntax:

cliq team install hub://@cliq/[email protected]

Without a version, the latest published version is installed.

Reinstalling

If the same version is already installed, cliq skips the download:

Already installed at v1.2.0. Use --force to reinstall.

Use --force to reinstall anyway:

cliq team install hub://@cliq/feature-dev-js --force

Installing a different version (or installing without a version pin when a newer version exists) overwrites the local copy.

Overwrite confirmation

When installing over an existing team (same @scope/name already installed), cliq prompts for confirmation — you must type the full team name to confirm the overwrite:

@acme/my-pipeline is already installed at v2.0.0. Source has v1.0.0.
Type the full team name to confirm:

Fresh installs (no existing team with that name) proceed without prompts. Use --force to skip all prompts.

Where teams live

Installed teams land under their scope in the global registry:

~/.cliqrc/teams/
├── @cliq/
│   ├── feature-dev-js/
│   │   ├── team.yml
│   │   ├── roles/
│   │   └── .cliq-source
│   └── hello-world/
├── @someorg/
│   └── data-pipeline/
└── @local/
    └── my-experiment/

Each installed team has a .cliq-source file tracking how it was installed (hub or local path).

Using a team

Once a team is installed, use it in any project with three commands:

1. Assemble

cliq assemble @cliq/feature-dev-js

This copies the team’s workflow and role files into the project’s .cliq/ directory. After assembly, the project is self-contained — cliq run reads only from .cliq/, not from the registry.

If the project doesn’t have a .cliq/ directory yet, run cliq init first.

2. Set the requirement

cliq req -m "Add user authentication with OAuth2 PKCE flow"
cliq req -s requirements.md

Use -m for a one-liner or -s for a file. The requirement is written to .cliq/req_spec.md.

3. Run

cliq run

The orchestrator launches each phase in dependency order, manages gate verdict loops, and reports the outcome.

Listing installed teams

cliq team list

Teams:

  @cliq
    feature-dev-js   v1.2.0  (hub)
    hello-world      v1.0.0  (hub)

  @local
    my-experiment    v1.0.0  (local)

Inspecting a team

cliq team info @cliq/feature-dev-js
cliq team info hub://@cliq/feature-dev-js

The first shows local details; the second fetches registry metadata including version history and update availability.

Preflight requirements

Tools

When a team declares tools in team.yml, the orchestrator runs a preflight check before any agent launches. For each tool, it checks whether it’s on PATH. If any tool is missing, the pipeline immediately escalates with a clear error.

tools: ["git", "npm", "docker"]

cliq_version

When a team declares cliq_version, the parser verifies the running cliq version satisfies the semver range before assembly or execution.

cliq_version: ">=1.0.0"

cliq doctor

Run cliq doctor in any project to check all dependencies — both cliq’s own requirements (tmux, node, git, etc.) and the assembled team’s tools and runtime agent binaries.

  Checking dependencies...

  tmux... ✓ (tmux 3.3a)
  node... ✓ (v20.11.0)
  git... ✓ (git version 2.43.0)

  Agents:
  agent... ✓ (Cursor 0.45.0)

Team resolution

When cliq resolves a team name (in cliq assemble, cliq team info, etc.), it searches the default registry (~/.cliqrc/teams/).

If a fully qualified name is given (e.g. @cliq/feature-dev-js), resolution skips directly to the specified scope.

When a bare name is used (e.g. cliq assemble feature-dev-js without a scope), cliq searches @local first, then other @* scopes alphabetically. If the name exists in exactly one location, it resolves there and the CLI shows which scope was matched:

Resolved feature-dev-js → @cliq/feature-dev-js

If the same bare name exists in multiple scopes (e.g. both @local/feature-dev-js and @cliq/feature-dev-js), cliq raises an error and asks you to use the fully qualified @scope/name:

Team 'feature-dev-js' found in multiple locations:
  @local/feature-dev-js (/Users/you/.cliqrc/teams)
  @cliq/feature-dev-js (/Users/you/.cliqrc/teams)
— use an explicit @scope/name.

There is no implicit priority between scopes. If there’s ambiguity, you must be explicit.

Updating teams

Update all installed teams

cliq team update

This scans 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 filesystem path. Teams without provenance (legacy installs) are skipped.

Updates available:

  @cliq/feature-dev-js  1.2.0 → 1.3.0  (minor)     [hub]
  @cliq/hello-world     1.0.0 → 2.0.0  (major ⚠)   [hub]
  @local/my-team        1.0.0 → 1.1.0  (minor)      [local]

Already up to date:
  @cliq/discovery  1.1.0

Apply updates? [y/N]

Major version bumps are flagged with a warning since they may contain breaking changes.

Update a specific team

cliq team update @cliq/feature-dev-js

Skip the confirmation prompt

cliq team update --force

What gets skipped

Teams without .cliq-source (legacy installs) — no provenance, no update target
Teams not found in their source (registry or path) — get a warning but don’t block other updates
Teams without a local version are treated as 0.0.0 for comparison purposes

Checking for updates

cliq team info

cliq team info hub://@cliq/feature-dev-js

Shows full team metadata from the registry including version history and your locally installed version. If a newer version is available, you’ll see an update hint:

Installed:  v1.2.0  ~/.cliqrc/teams/@cliq/feature-dev-js
  ↑ Update available: v1.3.0 — run `cliq team update @cliq/feature-dev-js`

Version history

The info command shows all published versions with dates and changelogs:

Versions:
  v1.3.0  Apr 15, 2026  (latest)
    Improved reviewer checklist for edge cases
  v1.2.0  Mar 20, 2026
    Added security review phase
  v1.0.0  Jan 10, 2026

The same history is available on the team’s detail page at cliqhub.io.

Provenance tracking

Every install writes a .cliq-source JSON file inside the team directory:

{
  "source": "hub",
  "registry": "https://cliqhub.io",
  "version": "1.2.0",
  "installed_at": "2026-04-15T10:30:00Z"
}

For local installs:

{
  "source": "local",
  "path": "/Users/you/projects/my-team",
  "version": "1.0.0",
  "installed_at": "2026-04-15T10:30:00Z"
}

This marker is used by cliq team update to determine where to check for newer versions and by cliq team list to display the source column.

Customizing installed teams

Installed teams are read-only by convention — updates will overwrite them. To customize a team:

Fork to a local directory

cliq team copy @cliq/feature-dev-js ./my-feature-dev

Edit your copy freely, then install it under @local/:

cliq team install ./my-feature-dev

Teams under @local/ are never touched by cliq team update.

Fork to your own scope

cliq team copy @cliq/feature-dev-js ./feature-dev @myorg

This copies the team and rewrites the scope in team.yml to @myorg. Install and publish your fork under your own scope:

cliq team install ./feature-dev
cliq team publish ./feature-dev

See Publishing.

Uninstalling

Remove an installed team:

cliq team uninstall @cliq/feature-dev-js
cliq team uninstall @local/my-experiment

This deletes the team directory from ~/.cliqrc/teams/, including the .cliq-source marker.

Command reference

Command	Description
`cliq team install hub://<team>`	Install latest version from registry
`cliq team install hub://<team>@1.2.0`	Install specific version
`cliq team install <path>`	Install from local path
`cliq team install <source> --force`	Reinstall even if same version
`cliq team update`	Update all installed teams
`cliq team update <team>`	Update a specific team
`cliq team update --force`	Skip confirmation prompt
`cliq team info hub://<team>`	Show registry details, versions, update status
`cliq team list`	List all installed teams, grouped by scope
`cliq team copy <source> <dest> [scope]`	Copy a team to a local directory for customization
`cliq team uninstall <team>`	Remove an installed team
`cliq assemble <team>`	Deploy a team to the current project’s `.cliq/` directory