---
name: clarive
description: Work with a Clarive DevOps server through its MCP tools or the clarive CLI. Covers topics and changesets, deployment jobs and their logs, pipeline rules as HCL, resources (servers, CIs), approvals, environments, users and roles. Use when the user mentions Clarive, a topic or changeset mid, a job such as JOB-00012, a Clarive rule, an environment such as QA or PROD, or asks to deploy, promote, approve, roll back or explain a failure in Clarive.
compatibility: Needs Clarive 7.22.2 or later, reached through its MCP server (https://<server>/mcp, or the local bridge `clarive mcp`) or the `clarive` CLI.
metadata:
  publisher: clarive.com
  version: "1.0"
---

# Clarive

Clarive publishes one set of operations, the Clarive API, three ways: REST at
`/api/v2`, an MCP server at `/mcp` and the `clarive` CLI. They share names,
parameters, permissions and errors. The operation `job.logs` is the MCP tool
`job_logs` and the command `clarive job logs`. Everything runs as the user who
owns the token, with that user's roles, exactly as in the web interface.

## Which door you have

- **MCP tools** are named `<namespace>_<op>`: `topic_search`, `job_get`,
  `hcl_get_rule`. The list only holds what this user may call. A read token,
  or the server's `read_only` option, leaves only tools that change nothing.
- **Compact mode** leaves four tools: `api_namespaces`, `api_search`,
  `api_describe` and `clarive_call`. Call any operation through
  `clarive_call` with `op` (the dotted name, `job.list`) and `params` (an
  object).
- **Namespaces.** A server connected with the `namespaces` option lists only
  those namespaces. `api_search` and `api_describe` stay only when `api` is
  one of them. If a tool you need is missing, tell the user which namespace
  holds it.
- **The CLI** is `clarive <namespace> <op> [positional args] [--flags]`, with
  underscores turned into dashes (`clarive job list-transitions`). Piped
  output is JSON. Add `-o json` in scripts anyway. `clarive api call job.list
  limit=5` calls any operation by name.

If several Clarive servers are connected (for example `clarive-test` and
`clarive-prod`), say which one you are reading from every time, and never copy
a change from one to the other without the user asking.

## Find the operation before you guess

1. `api_search` with a few words ("job log", "topic status"). It can filter by
   `namespace` and by `kind` (`read`, `write`, `destructive`). CLI:
   `clarive api search job log`.
2. `api_describe` with the dotted name (`job.logs`) before the first call of an
   operation you have not used in this session. It gives the parameters, their
   schema, the kind and the permission. CLI: `clarive api describe job.logs`.
3. Call it with the parameter names from the schema. Never invent one.

An `invalid_params` error lists every wrong parameter. Read it, fix them all
and try once more. A `not_found` for an operation name in `clarive_call`
suggests operations from the same namespace or with a similar name.

## Identifiers and lists

- Topics (changesets, releases, issues), jobs and resources go by their
  `mid`. Jobs also go by name (`JOB-00012`). Statuses, categories, projects
  and labels go by name or id. Environments are `bl` names: `QA`, `PROD`.
- `ci_get_many` reads several mids of any classes in one call.
- `topic_search` takes `assigned_to_me`, `assigned_to`, `created_by`,
  `only_open`, `categories`, `statuses`, `projects` and a text `query`.
- Lists answer `{items, total, skip, limit}`. The default page is 50 and the
  most is 1000. For a count, ask for `limit: 1` and read `total`. Page with
  `skip`.
- Answers over 256 KB are cut with a note. Ask for less: a smaller `limit`, a
  filter, one page at a time, `levels: ["error"]` on a log.

## Jobs return at once, then you poll

- Before deploying: `job_list_transitions` (where a changeset may go),
  `calendar_check_window` with the changesets (when the environment is open
  for them; without changesets it reads only the global calendars) and
  `job_estimate`.
- `job_create` with `bl` and `changesets` runs the CHECK and INIT steps and
  returns. It does not wait for the deployment.
- Follow a job with `job_get` for its status. Read its log with `job_logs`,
  passing back the `next_since_id` of the previous answer as `since_id`. Stop
  when `finished` is true and `has_more` is false. Leave a few seconds between
  polls and report progress in a line or two, not the whole log.
- With the CLI, `clarive job create QA 101 --wait --logs` and
  `clarive job wait JOB-00012` exit 0 when the job finished OK and 9 when it
  ended any other way. `clarive job logs JOB-00012 --follow` prints the log
  until the job ends.
- `server_execute`, `ci_run_service` and `rule_run` do wait for the command,
  within their own timeout.
- A job scheduled outside every deployment window of its environment is
  refused with `forbidden`. Pick a time inside a window. `no_cal: true` skips
  the calendar, needs its own permission and a reason in `comments`. Never pass
  it unless the user asks for an out-of-window job and gives the reason. An
  environment with no calendar at all counts as outside, and so does a window
  of the other `window_type` (N normal, U urgent). The error says which.

## Why a job failed

1. `job_get` for its status, step and environment.
2. `job_get_root_cause`. It returns what Clarive's Root Cause resources matched
   in the log after the job ended. It can be empty when none match or the
   analysis daemon is off. Empty is not the same as "no problem".
3. `job_logs` with `levels: ["error"]` (then `["warn", "error"]`), and
   `job_get_summary` for each service's result by step.
4. `job_runner_log` for the raw output of the process, when the user has the
   permission for it.

Recovery changes things, so propose it and wait for a yes:
`job_trap_action` (`retry`, `skip`, `pause` or `error`) for a job that is
TRAPPED, and `job_restart` with a `step` for a job that has ended.

## Topics and their statuses

- `topic_list_next_statuses` shows where a topic may go. Then
  `topic_change_status` with `mid` and `status`. If the status asked for is
  not in that list, call `topic_explain_status_change` instead of trying.
- If a change is refused, call `topic_explain_status_change`. It returns the
  reasons with codes (`no_transition`, `missing_role`, `deploy_only`,
  `required_field` and others) and changes nothing. Report them. Do not try
  other statuses or fields to get around a refusal.

## Rules are HCL text: read, check, save with base_version

1. `hcl_get_rule` with the rule's id or name. Keep its `version_id`.
2. Edit the text. Write HCL, never rulebook YAML. `rule_describe_operation`
   gives one operation's fields, defaults and HCL spelling.
   `rule_list_operations` lists the operations.
3. `hcl_check` with the text and `rule` for syntax, meaning, compile and the
   rule critic. Fix every error it reports by line and column. Read `ok`
   and `compiled` in the answer: with a read token, or without the right to
   modify that rule, nothing is compiled, so say so instead of reporting a
   clean check.
4. Show the user the change as a diff and wait for a yes.
5. `hcl_save_rule` with `hcl`, `rule` and `base_version` set to the
   `version_id` you read. A `conflict` means someone saved in between. Read
   the rule again, redo the change on the new text and show it again. Never
   pass `overwrite: true` unless the user says so after seeing the conflict.

Every save is a new version. `rule_list_versions`, `rule_diff_versions` and
`rule_restore_version` show and undo changes. CLI: `clarive rule edit 42`
does the whole round trip, and `clarive rule get 42 --hcl` prints the text.

Never put a password, token or key in an `sh` step or any command line. The
job log keeps the command line with its variables expanded.

## Read first, ask before you change anything

- Read the current state before any write and tell the user what will change.
- Each tool says whether it is read-only or destructive (`api_describe` shows
  the `kind`). Call write tools only for what the user asked. Ask before every
  destructive tool, which deletes or overwrites, even when you were told to
  "clean up".
- Ask first, every time, before tools that act on real machines or bypass
  review, whatever their kind: `server_execute`, `worker_execute`, `file_put`,
  `file_write`, `file_sync`, `file_delete`, `rule_run`, `ci_run_service`,
  `job_create` to PROD, `job_rollback`, `job_cancel`, `job_approve`,
  `job_reject` and `repl_eval`.
- With the CLI, ask the user in the chat before every destructive command,
  and add `--yes` (`-y`) only after they said yes. Don't count on the CLI to
  ask for you: your shell is usually not a terminal.
- `forbidden` means the user lacks a permission. Report it with the
  permission `api_describe` names. Never look for another tool that does the
  same thing.
- `forbidden: ... event.mcp.call stopped it: ...` means a rule at this site
  refused the call. Report the rule's message as it is and stop.
- Every MCP tool call is recorded in the `event.mcp.call` audit event, with
  the user, the tool, the arguments (secrets masked) and the answer.

## Secrets

- Never print, repeat, store or log a token (`clapat_...`), password or key.
  Never ask the user to paste one into the chat. They run `clarive login`
  themselves, or put the token in their client's secret storage or an
  environment variable.
- Secrets come back masked. Sending the masked value back in an update keeps
  the stored one, so leave masked values alone.
- Do not use `variable_get` with `reveal` unless the user asks for it.

## When something does not work

- First check: `auth_whoami` (CLI: `clarive whoami`) shows the user, the token
  and its roles.
- `401` or `unauthorized`: the token expired or was revoked. The user runs
  `clarive login` again, or makes a new token.
- A tool you expected is missing: the user lacks its permission, the token is
  read-only, or the server was connected with `namespaces` or `read_only`.
  `clarive api describe <op>` shows the permission needed.
- `unavailable: Clarive is in maintenance mode`: only administrators get
  through until it ends.
- CLI exit codes: 0 ok, 1 failed or aborted, 2 usage or `invalid_params`,
  3 unauthorized, 4 forbidden, 5 not found, 6 conflict, 7 server error,
  8 network, 9 the job did not finish OK.

## Documentation

- MCP server: https://docs.clarive.com/en/mcp/overview/
- The clarive CLI: https://docs.clarive.com/en/cli/overview/
- Rules in HCL: https://docs.clarive.com/en/hcl/rules/