CLI - cliq

Reference

New to cliq? Do Get started first, then use this page as the flag bible. cliq is a thin client. Almost every command talks to cliqd, the local daemon, so start cliqd first. cliq team validate and cliq team version work on local files and need no daemon.

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

The generated, always-current list of every flag is cli/COMMANDS.md in the cliq repo.

Global options

Global options go before the command: cliq --verbose run.

Option	Description
`-V, --version`	Print the cliq version
`--verbose`	Print debug lines, error codes, request ids and stack traces
`--no-color`	Print without colours (also `NO_COLOR=1`)
`-h, --help`	Show help for a command

Most commands also take --json (machine-readable output). Commands that act on a workspace take -w, --workspace <ref> (workspace id, name or path; default: the current directory). Destructive commands take -y, --yes.

Exit codes

Code	Meaning
`0`	OK
`1`	Error (cliqd, CliqHub or a local check failed)
`2`	Usage (bad flag, argument or value)
`3`	Input required (pass the missing inputs, e.g. `-i key=value`)
`130`	Interrupted

Environment

Variable	Description
`CLIQ_DAEMON_HOST`, `CLIQ_DAEMON_PORT`	cliqd endpoint (default `127.0.0.1:4900`)
`CLIQ_DAEMON_TOKEN`	Bearer for a remote cliqd (see Talking to a remote cliqd)
`CLIQ_API_URL`	CliqHub API base, read by cliqd (default `https://api.cliqhub.io`)
`CLIQ_HOME`	Settings directory (default `~/.cliqrc`)
`CLIQ_DEBUG=1`	Same as `--verbose`
`NO_COLOR=1`	Same as `--no-color`

Auth & identity

Log in to CliqHub through cliqd. cliqd must be running. cliqd keeps the session; the CLI stores nothing. The first login also enrolls cliqd in a realm: the one you pass with --realm, your only realm, or one you pick from a list. Once enrolled, the realm is locked: a later login keeps it. To move cliqd, start it with --allow-realm-override and run cliq login --realm <org.slug>. Never do that while runs are in progress.

Option / arg	Description
`--headless`	Log in without prompts, using `username:<name>` `password:<password>` arguments. A new cliqd joins your default realm.
`--realm <org.slug>`	Enroll cliqd in this realm (moving an enrolled cliqd needs `cliqd --allow-realm-override`)
`-y, --yes`	Confirm moving cliqd to another realm without asking
`--json`	Print the result as JSON

cliq login
cliq login --realm acme.ops
cliq login --headless username:alice password:secret

The CliqHub URL belongs to cliqd: set it with cliqd --hub <url> or CLIQ_API_URL.

`cliq logout`

Log out of CliqHub. cliqd keeps its daemon token and its realm; log in again with cliq login. Takes --json.

`cliq whoami`

Show the daemon identity (id, version, uptime, host), the CliqHub user, orgs, realms (* marks cliqd’s realm), team scopes and tokens. --json prints the full daemon status. When CliqHub refuses a team because it is not on the realm’s team list, whoami lists it:

  Not syncing these teams' runs — not on this realm's team list: @acme/my-team
    Runs of other teams still sync. These wait on this machine until the team is allowed.
    Add them to the realm in CliqHub or uninstall them (`cliq team uninstall`).

See How teams get installed.

`cliq setup`

Guided setup: log in to CliqHub, set the Hub URLs, and configure agent credentials. Agent credentials are saved in cliqd, so start it first.

Option	Description
`--reset`	Log in again even when already logged in
`--non-interactive`	Accept every default without prompting (skips login and agents)

cliq setup
cliq setup --reset
cliq setup --non-interactive

`cliq auth token <name>`

Create a CliqHub API token. Needs cliq login. The token is printed once. Without --realm it is a durable user PAT (cliq_tok_…) for CI. With --realm it is a realm enrollment token (cliq_dt_…) for headless daemons.

Option	Description
`--realm <realm_id>`	Mint a realm enrollment token (`cliq_dt_…`) instead of a user PAT
`--json`	Print the result as JSON

cliq auth token ci-publish
cliq auth token prod-enroll --realm <realm_id>

To log a cliqd in with a user PAT instead of a password (CI, containers):

echo '<cliq_tok_…>' | cliq settings set cliq.api_key --stdin

Only durable user PATs (cliq_tok_…) are accepted there.

`cliq auth rotate-dispatch`

Rotate a realm’s dispatch key pair and print the new public PEM (realm admins). Daemons in the realm pick up the new key on their next heartbeat.

Option	Description
`--realm <realm_id>`	Required — realm whose dispatch key to rotate
`--json`	Print the result as JSON

cliq auth rotate-dispatch --realm <realm_id>
cliq auth rotate-dispatch --realm <realm_id> > dispatch.pem

Realm management (create, members, team list) is done in the CliqHub web UI. See Realms.

Talking to a remote cliqd

By default the CLI talks to cliqd on 127.0.0.1:4900 and needs no credential. To reach a cliqd on another host (or behind a Docker port mapping), set CLIQ_DAEMON_HOST / CLIQ_DAEMON_PORT and CLIQ_DAEMON_TOKEN. The token must be one that cliqd accepts:

a local token (cliq_…) minted on the machine running that cliqd (Local tokens), or
a user PAT (cliq_tok_…) of a user in that cliqd’s realm, when cliqd is connected to CliqHub.

Agents

List local agents and register them on CliqHub. cliqd looks for agents on CLIQ_AGENTS_PATH (colon-separated), else the agents.path setting, and always adds ~/.cliqrc/agents last. Built-in agents ship with cliqd and refresh when you upgrade and restart it.

`cliq agent list`

List the agents on the local agents path (no CliqHub call unless --check-reg).

Option	Description
`--path`	Print the agents search path instead of the agents
`--check-reg`	Also show whether each agent is registered on CliqHub
`-l, --long`	Include each agent’s description
`--json`	Print the result as JSON

cliq agent list
cliq agent list --long
cliq agent list --check-reg
cliq agent list --path

`cliq agent info <name>`

Show one agent: version, type, directory and manifest. Takes --json.

cliq agent info jira
cliq agent info my-custom-linter --json

`cliq agent register <name_or_path>`

Register a local agent on CliqHub from its manifest. Pass an agent name on the agents path, or a path to the agent directory.

Option	Description
`--force`	Overwrite an existing registration
`--json`	Print the result as JSON

cliq agent register my-linter
cliq agent register /path/to/my-agent
cliq agent register my-linter --force

`cliq agent unregister <name>`

Remove an agent (or one version of it) from CliqHub.

Option	Description
`--agent-version <version>`	Remove only this version (omit to remove every version)
`--json`	Print the result as JSON

cliq agent unregister my-linter
cliq agent unregister my-linter --agent-version 0.3.0

There is no cliq agent install, uninstall, update, reload or build. Built-in upgrades come with a new cliqd. Configure credentials with cliq setup or cliq settings set agents.<name>.<key> <value>.

Creating a custom agent

Build agents with @getcliqio/cliq-sdk (GitHub Packages). The SDK handles the agent protocol; you implement phase handlers. 1. Install the SDK

# Auth once (GitHub PAT with `read:packages`)
echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> ~/.npmrc
echo "@getcliqio:registry=https://npm.pkg.github.com" >> ~/.npmrc

mkdir -p ~/.cliqrc/agents/my-linter && cd ~/.cliqrc/agents/my-linter
npm init -y
npm install @getcliqio/cliq-sdk

Package: @getcliqio/cliq-sdk · source: getcliqio/cliq-sdk. 2. Agent layout

my-linter/
  package.json          # depends on @getcliqio/cliq-sdk
  manifest.json         # name, version, agent_type, entry, settings, …
  index.js              # CliqAgent handlers

Minimal manifest.json:

{
  "name": "my-linter",
  "version": "0.1.0",
  "agent_type": "exec",
  "entry": "./index.js",
  "description": "Custom linter phase"
}

3. Check and register Put the directory on the agents path (CLIQ_AGENTS_PATH, agents.path, or ~/.cliqrc/agents), then:

cliq agent list
cliq agent info my-linter
cliq agent register my-linter

CliqHub stores catalog metadata only. The code stays on the machines whose agents path holds it. Agent types and built-ins: Agents.

Workspace & runs

Each workspace command also exists under cliq workspace (cliq init = cliq workspace init, and so on).

`cliq init [path]` / `cliq workspace init`

Option	Description
`--name <name>`	Workspace name: letters, digits, spaces, `-` `_` `.` (max 64)
`--json`	Print the result as JSON

`cliq status` / `cliq workspace status`

Show a workspace: path, assembled teams, last and active runs. In a directory that is not a workspace, it lists every registered workspace.

Option	Description
`-w, --workspace <ref>`	Workspace id, name or path
`--all`	List every registered workspace
`--config [team_ref]`	Show a team’s assembly-time settings (team ref optional when one team is assembled)
`--unmask`	With `--config`: show secret values in full
`--json`	Print the result as JSON

`cliq workspace list`

List every workspace registered with cliqd: name, id, path, teams and last run.

Option	Description
`--runs`	Show each workspace’s recent runs
`--last <n>`	With `--runs`: how many runs per workspace (default 5)
`--json`	Print the result as JSON

`cliq assemble <team_ref>` / `cliq workspace assemble`

Bind an installed team (@scope/slug, see cliq team list) to a workspace. A workspace can hold several teams; cliq run -t picks one.

Option	Description
`-w, --workspace <ref>`	Workspace id, name or path
`--json`	Print the result as JSON

`cliq disassemble <team_ref>` / `cliq workspace disassemble`

Unbind a team from a workspace. The team stays installed. Takes -w and --json.

`cliq workspace delete`

Deregister a workspace from cliqd and the CliqHub catalog. Files on disk are kept, and so are its runs (still in cliq logs and CliqHub). Refused while a run is in progress there. Removal from the CliqHub catalog is best effort (only when cliqd is enrolled).

Option	Description
`-w, --workspace <ref>`	Workspace id, name or path
`-y, --yes`	Delete without asking (required when stdin is not a terminal)
`--purge`	Also remove the workspace’s `.cliq/` folder (project files are never touched)
`--json`	Print the result as JSON

`cliq clean` / `cliq workspace clean`

Delete a workspace’s finished runs. Keeps the workspace, its teams and active runs. To deregister the workspace, use cliq workspace delete. Takes -w and --json.

`cliq run [run_id] [phase]`

Run the workspace’s team and stream its progress. With run_id and phase, rerun that run from the phase instead.

Option	Description
`-n, --name <name>`	Name for the run (generated when omitted)
`-t, --team <team_ref>`	Which assembled team to run (needed when several are assembled)
`-w, --workspace <ref>`	Workspace id, name or path
`-i, --input <key=value>`	An input for the team (repeatable)
`--label <key=value>`	A label recorded with the run (repeatable)
`--context-id <id>`	External correlation id; reuses the active run with the same id
`--no-stream`	Return once the run starts instead of streaming its events
`--json`	Print the started run as JSON (implies `--no-stream`)

Exit code 0 when the run completes, 1 when it fails, 3 when inputs are missing. Follow a run later with cliq logs -f.

cliq run
cliq run -i task="Write a haiku" -i lang=en
cliq run --name my-feature --team @acme/feature-dev
cliq run --context-id "$CI_JOB_ID" --label env=prod
cliq run bold-arch scaffold-parser

If the team is not on the realm’s team list, the run still starts and runs on this machine, but cliq run warns that it won’t appear in CliqHub yet:

This run won't appear in CliqHub: @acme/my-team isn't installed in this realm. It runs here and syncs once a realm admin adds the team to the realm in CliqHub.

With --json the same text is in the warnings array. See How teams get installed.

`cliq logs [run_id]`

Show a run’s log (default: the latest run, with its sub-runs), list recent runs, or follow live.

Option	Description
`-f, --follow`	Follow the log as it is written (Ctrl+C to stop). Without a run id, follows the latest run, then each new one.
`--last <n>`	List the last n runs instead of showing a log
`--flat`	Show the run’s own log only, without its sub-runs
`--json`	Print the log (or with `--last`, the runs) as JSON

Outbox (daemon → Hub delivery queue)

cliqd queues every state change bound for CliqHub (runs, teams, workspaces, events) in a durable SQLite outbox. It ships them in order, with retry and exponential backoff. When something upstream breaks (Hub outage, revoked auth, schema drift), entries pile up and can run out of retries. They are then dead. Runs of a team that is not on the realm’s team list are held back on their own. They do not block other teams’ runs. See How teams get installed. There is no cliq outbox command and no admin API for the outbox. cliqd emits daemon.outbox.dead and daemon.outbox.recovered into the Hub event catalog when the dead count changes. Wire notification rules on those types for alerts.

Teams (daemon catalog)

A team ref is @scope/slug. A team directory holds team.yml (plus roles/, dependencies.yml, Dockerfile).

`cliq team install <source>`

Install a team into cliqd’s catalog from CliqHub (@scope/slug[@version]) or a directory (./dir, ../dir, /abs/dir). Teams outside the @local scope (also from directories) need cliq login.

Option	Description
`--team-version <version>`	Directory: version to record (default: team.yml’s). Ref: version to fetch
`--description <text>`	Directory: description to record (default: team.yml’s)
`--force`	Overwrite the team if it is already installed
`--json`	Print the result as JSON

cliq team install @cliq/hello-world
cliq team install @acme/[email protected]
cliq team install ./my-team --force

`cliq team uninstall <team_ref>`

Remove a team from the catalog. Workspaces using it lose it.

Option	Description
`-y, --yes`	Required — confirm the removal
`--force`	Allow uninstalling a Hub-origin team
`--latest`	When multiple versions exist, target the latest
`--json`	Print the result as JSON

`cliq team list [scope]`

List the installed teams, grouped by scope. Pass a scope (without the @) to filter. Takes --json (includes manifests).

`cliq team info <team_ref>`

Show an installed team’s metadata and manifest. Takes --json.

`cliq team update <team_ref>`

Replace an installed team’s manifest from its source directory. Reinstall from a directory with cliq team install <dir> --force for a full replacement.

Option	Description
`--team-version <version>`	Version to record (default: the manifest’s)
`--description <text>`	Description to record (default: the manifest’s)
`--latest`	When multiple versions exist, target the latest
`--json`	Print the result as JSON

`cliq team export [team_refs...]`

Write installed teams to disk, one folder per team (team.yml, Dockerfile, dependencies.yml). Edit the files, then install them again with cliq team install ./<dir>.

Option	Description
`-d, --dir <path>`	Output directory (default: the current directory)
`--all`	Export every installed team

`cliq team validate [dir]`

Check a team directory: team.yml, its file:// references and dependencies. Defaults to the current directory. No daemon needed. Exit code 1 when anything is invalid. Takes --json.

`cliq team version [dir]`

Print the version in a team directory’s team.yml, or bump it. No daemon needed. Only the version line changes; comments and formatting are kept.

Option	Description
`--patch`	Bump `X.Y.Z` → `X.Y.Z+1`
`--minor`	Bump `X.Y.Z` → `X.Y+1.0`
`--major`	Bump `X.Y.Z` → `X+1.0.0`

cliq team version                  # print the version in ./team.yml
cliq team version ./my-team --patch
cliq team version ./my-team --minor

`cliq team publish <dir>`

Publish a team directory to CliqHub. It does not install it locally. Publishing an already-published version is skipped (exit 0); bump it with cliq team version <dir> --patch.

Option	Description
`--access <level>`	`draft` \| `public` \| `private` (default: `public`)
`--message <text>`	Changelog message for this version
`--hub <url>`	CliqHub API URL to publish to (default: the one cliqd uses)
`--dry-run`	Validate and package without publishing
`--force`	Republish an existing version
`--json`	Print the result as JSON

cliq team publish ./hello
cliq team publish ./hello --message "fix null handling"
cliq team publish ./hello --dry-run
cliq team publish ./hello --access private

A published team runs anywhere, but its runs reach CliqHub only once the team is on the realm’s team list.

Instances

List, inspect and stop runs on this daemon.

Subcommand	Options
`list`	`--json`
`info <run_id>`	`--tree` (the full tree of nested runs), `--json`
`stop <run_id>`	`--json`

run_id is a run id or name. cliq instance stop marks the run cancelled and stops its work right away: the running agent process, any wait for inputs, and active sub-team runs. Cancelling from CliqHub does the same.

Settings & doctor

`cliq settings`

Read and write settings. Everything is stored in cliqd; there is no ~/.cliqrc/settings.json. Keys under agents., hub., hub_connect., daemon., logging., cliq. and other daemon prefixes are daemon-wide. Any other key is a secret of the workspace in the current directory. A few keys are handled specially:

Key	Behaviour
`cliq.api_key`	`set` logs cliqd in with a durable user PAT (`cliq_tok_…`); `--unset` logs out; `get` shows it masked
`daemon.id`	Read-only (set by cliqd; `cliqd --reset-id` gives a new one)

cliq login keeps its session in cliqd (hub.session, never listed).

Form	Description
`cliq settings`	List every setting (secrets masked)
`cliq settings get <key>`	Read one key, or every key under a section. Exit code `1` and `(not set)` when it has no value.
`cliq settings set <key> <value>`	Write a value
`cliq settings set <key> --unset`	Remove a key (restores its default, if it has one)
`cliq settings set <key> <value> --add`	Append to an array setting
`cliq settings set <key> --stdin`	Read the value from stdin (secrets, scripts)
`--unmask`	Show secret values in full (on `settings` or `settings get`)
`--json`	Print the result as JSON

Options of cliq settings itself go before a subcommand (cliq settings --json); get and set have their own.

cliq settings
cliq settings get agents.git.github.base_branch
cliq settings set agents.git.github.base_branch develop
echo "$TOKEN" | cliq settings set agents.cursor.api_key --stdin
cliq settings set agents.git.github.pr_labels v2 --add
cliq settings set agents.git.github.pr_draft --unset
cliq settings set hub_connect.sync false
cliq settings --unmask

Agent credentials (agents.jira.api_token, agents.cursor.api_key, …) are daemon settings. Required keys per agent: Agents.

`cliq doctor`

Check cliqd, agents, workspaces and teams, and say what to fix. Exit code 1 when a check fails. --json prints the raw result.

cliq doctor
cliq doctor --json

The daemon → cliqd
Local development → Local Development
Credentials → Auth
Logs on disk → Logging

​Global options

​Exit codes

​Environment

​Auth & identity

​cliq login [credentials...]

​cliq logout

​cliq whoami

​cliq setup

​cliq auth token <name>

​cliq auth rotate-dispatch

​Talking to a remote cliqd

​Agents

​cliq agent list

​cliq agent info <name>

​cliq agent register <name_or_path>

​cliq agent unregister <name>

​Creating a custom agent

​Workspace & runs

​cliq init [path] / cliq workspace init

​cliq status / cliq workspace status

​cliq workspace list

​cliq assemble <team_ref> / cliq workspace assemble

​cliq disassemble <team_ref> / cliq workspace disassemble

​cliq workspace delete

​cliq clean / cliq workspace clean

​cliq run [run_id] [phase]

​cliq logs [run_id]

​Outbox (daemon → Hub delivery queue)

​Teams (daemon catalog)

​cliq team install <source>

​cliq team uninstall <team_ref>

​cliq team list [scope]

​cliq team info <team_ref>

​cliq team update <team_ref>

​cliq team export [team_refs...]

​cliq team validate [dir]

​cliq team version [dir]

​cliq team publish <dir>

​Instances

​Settings & doctor

​cliq settings

​cliq doctor

​Related