> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcliq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Every cliq command, subcommand, and option.

<div className="cliq-kicker">Reference</div>

New to cliq? Do [Get started](/get-started) first, then use this page as the flag bible.

`cliq` is a thin client. Almost every command talks to [cliqd](/cliqd), the local daemon, so start `cliqd` first. `cliq team validate` and `cliq team version` work on local files and need no daemon.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq --help
cliq <command> --help
cliq <command> <subcommand> --help
```

The generated, always-current list of every flag is [`cli/COMMANDS.md`](https://github.com/getcliqio/cliq/blob/main/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](#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

### `cliq login [credentials...]`

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 |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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](/cliqd#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) |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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 |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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):

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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 |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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](/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](/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 |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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`.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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 |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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 |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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**

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# 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`](https://github.com/getcliqio/cliq-sdk/pkgs/npm/cliq-sdk) · source: [getcliqio/cliq-sdk](https://github.com/getcliqio/cliq-sdk).

**2. Agent layout**

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
my-linter/
  package.json          # depends on @getcliqio/cliq-sdk
  manifest.json         # name, version, agent_type, entry, settings, …
  index.js              # CliqAgent handlers
```

Minimal `manifest.json`:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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](/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`

Register a directory as a workspace (default: the current directory). Re-running on a registered directory is safe.

| 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`.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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](/cliqd#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](/cliqd#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 |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq team install @cliq/hello-world
cliq team install @acme/my-parser@1.2.0
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. The ref is `@scope/slug[@version]`; when several versions are installed, name one or pass `--latest`.

| Option | Description |
| - | - |
| `--latest` | When multiple versions exist, pick the latest |
| `--json` | Print the result as JSON |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq team info @acme/review@1.2.0
cliq team info @acme/review --latest
```

### `cliq team update <team_ref>`

Replace the manifest of one installed version, in place. The ref is `@scope/slug[@version]`; when several versions are installed, name one or pass `--latest`. The version never changes: if the manifest declares a different `version:`, the update is refused — add a new version with `cliq team install <dir>` instead.

| Option | Description |
| - | - |
| `--manifest <path>` | **Required** — `team.yml` to store, or `-` for stdin (a sibling `dependencies.yml` is sent too) |
| `--description <text>` | Description to record (default: unchanged) |
| `--latest` | When multiple versions exist, target the latest |
| `--force` | Allow updating a Hub-installed team |
| `--json` | Print the result as JSON |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq team update @acme/review@1.2.0 --manifest ./review/team.yml
cliq team update @acme/review --latest --manifest ./review/team.yml
```

### `cliq team export [team_refs...]`

Write installed teams to disk, one folder per team (`team.yml`, `Dockerfile`, `dependencies.yml`). Refs are `@scope/slug[@version]`. 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` |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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 |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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](/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.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq doctor
cliq doctor --json
```

***

## Related

* The daemon → [cliqd](/cliqd)
* Local development → [Local Development](/local-development)
* Credentials → [Auth](/auth)
* Logs on disk → [Logging](/guides/logging)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.