@copado/agentia-cli 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -1,807 +1,468 @@
-# Copado Agentia CLI
+agentia-cli
+=================
 
-## Goal
+A new CLI generated with oclif
 
-The **Copado Agentia CLI** is the command-line entry point for interacting with Copado Agentia products: **CI/CD**, **robotic testing**, and **AI** capabilities exposed through **APIs**. The CLI wraps those services so teams can script pipelines, trigger tests, query or drive AI-assisted workflows, and integrate Agentia into local development and automation without building custom HTTP clients for every task.
 
-This repository is the Node.js + TypeScript implementation of that CLI. It includes a **Front API CICD proxy** client (`POST /json/v1/cicd-api`), **profile-based login** (token2 or CRT PAT), and commands for **connectivity checks** and **generic gateway invocation**.
+[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
+[![Version](https://img.shields.io/npm/v/agentia-cli.svg)](https://npmjs.org/package/agentia-cli)
+[![Downloads/week](https://img.shields.io/npm/dw/agentia-cli.svg)](https://npmjs.org/package/agentia-cli)
 
-## Prerequisites
-
-- **Node.js** `>= 18.18` (see `package.json` → `engines`)
-- **npm** (or another client compatible with `package-lock.json`)
-- **JDK 11+** on your `PATH` — only required when regenerating TypeScript clients from the OpenAPI specs with **`npm run codegen`** (or **`npm run build:openapi`**). Everyday **`npm run build`** does not run the generator; a fresh clone uses the committed output under [`src/generated/`](src/generated/).
-
-## How to execute
-
-### Install dependencies
 
-```bash
-npm install
+<!-- toc -->
+* [Usage](#usage)
+* [Integration Testing](#integration-testing)
+* [Local MCP Server](#local-mcp-server)
+* [or, from a local checkout:](#or-from-a-local-checkout)
+* [Commands](#commands)
+<!-- tocstop -->
+# Usage
+<!-- usage -->
+```sh-session
+$ npm install -g @copado/agentia-cli
+$ agentia COMMAND
+running command...
+$ agentia (--version)
+@copado/agentia-cli/0.1.0-alpha.2 darwin-arm64 node-v26.5.0
+$ agentia --help [COMMAND]
+USAGE
+  $ agentia COMMAND
+...
 ```
+<!-- usagestop -->
+# Integration Testing
 
-`prepare` runs `npm run build` after install, so `dist/` is produced automatically when dependencies are installed.
+Live metadata integration tests are opt-in. They use the CICD API key and endpoint already stored with `agentia auth set`, plus local Test14 IDs from `.env.integration`.
 
-### Build
-
-```bash
-npm run build
+```sh-session
+$ agentia auth set --cicd <api-key> --custom-url https://test.api.copado.com
+$ cp .env.integration.example .env.integration
+$ npm run test:integration
 ```
 
-Compiles TypeScript from `src/` to `dist/` and copies [`cicd_openapi.json`](cicd_openapi.json) and [`cicd_openapi.v2.json`](cicd_openapi.v2.json) into `dist/` so the CLI can resolve OpenAPI paths at runtime. Typed clients under [`src/generated/`](src/generated/) are **committed**; see [`src/generated/README.md`](src/generated/README.md).
+Fill `.env.integration` with the pipeline, org, credential, platform, metadata type, and API name values for the component you want to exercise. Do not commit `.env.integration`.
 
-```bash
-npm run build          # tsc + copy specs to dist/ (default; no codegen)
-npm run codegen        # regenerate src/generated/ — run when OpenAPI specs change
-npm run build:openapi  # codegen then build (spec change shortcut)
-npm run codegen:check  # fail if committed generated code is stale (CI / pre-push)
-```
+# Local MCP Server
 
-**Requirements for codegen:** Java (JDK 11+) on your `PATH` when you run `npm run codegen`; the `@openapitools/openapi-generator-cli` npm wrapper downloads the generator JAR on first use.
+Agentia can run as a local Model Context Protocol (MCP) server over stdio. MCP-compatible clients such as Cursor can then call Agentia tools without using the terminal.
 
-### OpenAPI spec changes (developer workflow)
+## Prerequisites
 
-Do **not** edit [`src/generated/`](src/generated/) by hand. When you change [`cicd_openapi.json`](cicd_openapi.json) or [`cicd_openapi.v2.json`](cicd_openapi.v2.json):
+1. Install or link the CLI so `agentia` is available:
 
-```bash
-npm run build:openapi   # or: npm run codegen && npm run build
-npm test
-# commit spec files + src/generated/
+```sh-session
+$ npm install -g agentia-cli
+# or, from a local checkout:
+$ npm run build && npm link
 ```
 
-| Step | What it does |
-|------|----------------|
-| `npm run codegen` | Regenerates `src/generated/cicd-v1` and `src/generated/cicd-v2` from the specs |
-| `npm run build` | Compiles the CLI and copies specs into `dist/` for discovery and schema-driven flags |
+2. Store CICD credentials. The MCP server reuses the same keychain-backed auth as the CLI:
 
-Codegen alone does **not** update `dist/`; build alone does **not** refresh `src/generated/` after a spec edit. Use both when the OpenAPI files change.
-
-For everyday CLI work (no spec changes), **`npm run build`** is enough.
-
-**Fresh clone:** `npm install` runs `prepare` → `npm run build` (compile + bundle specs). Generated clients come from git, not from install-time codegen.
-
-For toolchain details, scripts, and CI drift checks, see [docs/architecture/cicd-openapi-codegen.md](docs/architecture/cicd-openapi-codegen.md).
-
-
-### Run the CLI
+```sh-session
+$ agentia auth set --cicd <api-key> --custom-url https://test.api.copado.com
+$ agentia auth get
+```
 
-After a successful build, the binary is `dist/cli.js` and the published command name is **`agentia`**.
+3. Confirm the MCP command is available:
 
-```bash
-node dist/cli.js --help
-node dist/cli.js hello
+```sh-session
+$ agentia mcp --help
+$ agentia mcp start --help
 ```
 
-**Global `agentia` on your PATH (development):**
+## Start the server
 
-```bash
-npm link
-agentia --help
+```sh-session
+$ agentia mcp start
 ```
 
-## Front API CICD proxy
+This command is long-running. It speaks MCP over stdio and waits for a client connection. Do not expect interactive terminal output after start.
 
-The Salesforce deployer calls the same contract: **`POST {frontApiBaseUrl}/json/v1/cicd-api`** with JSON body:
+## Configure Cursor
+
+Add an MCP server entry that launches Agentia:
 
 ```json
 {
-  "endpoint": "<inner CICD Gateway path>",
-  "method": "<inner HTTP verb, e.g. GET or POST>",
-  "body": {}
+  "mcpServers": {
+    "agentia": {
+      "command": "agentia",
+      "args": ["mcp", "start"]
+    }
+  }
 }
 ```
 
-**Headers** depend on profile auth method (stored after `login`):
-
-**token2 profile:**
-
-- `Content-Type: application/json`
-- `token2` — value you provide at login (same header name as the deployer’s Front API calls)
-- `userId` — Salesforce user Id
-- `orgId` — Salesforce org Id
-
-**PAT profile:**
-
-- `Content-Type: application/json`
-- `X-Agentia-Authorization: PAT <token>` — CRT personal access token
-- `X-Agentia-Region: <crtRegion>` — CRT region saved on the profile at login (`QA`, `US`, `AU`, `EU`, or `SG`)
-- `X-Agentia-OrgId: <orgId>` — CRT organization id (required; resolved at `login pat` from Platform `/users/me`)
-
-The outer request is always **POST** to `/json/v1/cicd-api`; the **inner** `method` may be **GET** (for example `GET /health`) or **POST** (for example `POST /navigation/enabled` with a JSON body).
-
-**Migration:** PAT profiles saved before this header was mandatory may lack `orgId`. Re-run `agentia login pat` to resolve and store the organization id.
-
-## Regions and base URL
-
-Preset **regions:** `NA`, `NA2`, `EU` (default **NA**). Unless you pass **`--url`**, the Front API base URL is:
-
-`https://{na|na2|eu}.api.copado.com`
-
-Use **`--region CUSTOM` together with `--url https://…`** for hosts that are not covered by those presets, for example internal Front API hosts (`dev.api.copado.com`, `test.api.copado.com`, `test-cn.api.copado.com`) or customer-specific hosts (`tmobile.api.copado.com`, `emea-cn.api.copado.com`, and similar). The profile stores **`CUSTOM`** so it is clear the base URL was set explicitly.
-
-You can also pass **`--url`** alone with a preset region when your org uses a custom **Server_URL__c** (same idea as `DeployAPI.copadoURL` in the deployer).
+If Cursor cannot resolve `agentia` on `PATH`, use the absolute binary from this repo:
 
-## Configuration and login
-
-Profiles are stored under:
-
-- **macOS / Linux:** `$XDG_CONFIG_HOME/agentia/config.json` or `~/.config/agentia/config.json`
-- **Windows:** `%APPDATA%\agentia\config.json`
-
-The file is written with restrictive permissions where the OS allows.
-
-### `agentia login`
-
-Authenticate using a **subcommand** per auth method: **token2** (Front API legacy headers) or **pat** (CRT personal access token).
-
-#### `agentia login token2`
-
-```bash
-agentia login token2 \
-  --alias myorg \
-  --token2 '<your-token2>' \
-  --org-id '<Salesforce org Id>' \
-  --user-id '<Salesforce user Id>' \
-  --region NA
+```json
+{
+  "mcpServers": {
+    "agentia": {
+      "command": "/absolute/path/to/agentia-headless/cli/bin/run.js",
+      "args": ["mcp", "start"]
+    }
+  }
+}
 ```
 
-Optional **`--url https://...`** overrides the regional default host. For internal or customer-specific API hosts, use **`--region CUSTOM --url https://<host>`** ( **`--url` is required** for `CUSTOM`).
-
-#### `agentia login pat`
-
-Validates the PAT against the CRT Platform API (`GET /users/me`) before saving. The response is used to resolve and store a **CRT organization id** (`orgId`) on the profile; every PAT Front API call sends it as `X-Agentia-OrgId`.
+After saving the config, reload MCP servers in Cursor. The Agentia tools should appear in the MCP tool list.
 
-**Org resolution** (when `--org-id` is omitted):
+For local development, rebuild after code changes so Cursor picks up the latest `dist` output:
 
-| Situation | Selected org |
-|-----------|----------------|
-| One role in `/users/me` | That role's `organizationId` |
-| Multiple roles, `defaultOrg` in `private.settings` matches a role | `defaultOrg` |
-| Multiple roles, no matching `defaultOrg` | First role's `organizationId` |
-
-When `--org-id` is provided, it must match one of the user's role `organizationId` values (string compare); otherwise login fails.
-
-PAT profiles use two independent region settings:
-
-| Flag | Purpose |
-|------|---------|
-| **`--crt-region`** | CRT region for Platform validation and for `X-Agentia-Region` on Front API calls (default **QA**). Saved on the profile as `crtRegion`. |
-| **`--region` / `--url`** | Front API host (same rules as token2: `NA`, `NA2`, `EU`, or `CUSTOM` + `--url`). |
-
-```bash
-# Dev Front API host, QA CRT region
-agentia login pat \
-  --alias crt-dev \
-  --token "$CRT_PAT" \
-  --crt-region QA \
-  --region CUSTOM \
-  --url https://dev.api.copado.com
-
-# Production Front API (NA), US CRT region, explicit org
-agentia login pat \
-  --alias crt-prod \
-  --token "$CRT_PAT" \
-  --crt-region US \
-  --region NA \
-  --org-id "12345"
+```sh-session
+$ npm run build
 ```
 
-On success, the CLI prints the resolved `orgId` (for example `orgId: 1` when auto-selected from `/users/me`).
-
-Downstream commands (`cicd ping`, `cicd invoke`, etc.) use the **stored** `crtRegion` from the selected profile — there is no per-command `--crt-region` override.
+## Available tools
 
-The first profile saved becomes the **default profile** until you add more and change defaults (future enhancement: `config set-default`).
+Tools are JSON-safe and return structured results. Sensitive fields are redacted.
 
-### Choosing a profile
+| Topic | Tools |
+| --- | --- |
+| Environment | `agentia_environment_list`, `agentia_environment_get`, `agentia_environment_create`, `agentia_environment_update` |
+| Pipeline | `agentia_pipeline_list`, `agentia_pipeline_get`, `agentia_pipeline_connection_list` |
+| Project | `agentia_project_default_get`, `agentia_project_default_set`, `agentia_project_default_unset` |
+| Metadata | `agentia_metadata_list`, `agentia_metadata_content_get`, `agentia_metadata_content_compare`, `agentia_metadata_index_compare`, `agentia_metadata_dependency_list` |
 
-- Global option on any command: **`--profile <alias>`**
-- Environment variable: **`AGENTIA_PROFILE`**
+### Notes for common tools
 
-Example:
+- Pipeline tools require `userId` and `organizationId` for the gateway `x-user-id` and `x-organization-id` headers.
+- Metadata tools require the same gateway identifiers as the CLI flags, for example `pipelineId`, `sourceOrgId`, and `sourceCredentialId` where applicable.
+- Project default tools read and write local or global defaults managed by `agentia project default *`.
+- Environment create/update tools mirror the corresponding CLI commands and only send fields you provide.
 
-```bash
-agentia --profile staging cicd ping          # token2 profile
-agentia --profile crt-dev cicd ping          # PAT profile
-```
-
-## Commands (summary)
-
-| Command | Purpose |
-|---------|---------|
-| `login token2` | Save profile using token2 + orgId + userId + region + frontApiBaseUrl |
-| `login pat` | Save profile using CRT PAT; validates token; resolves orgId from `/users/me`; stores crtRegion + frontApiBaseUrl |
-| `cicd ping` | Inner **GET /health** through the proxy (connectivity) |
-| `cicd invoke` | Call any inner endpoint/method/body through the proxy |
-| `cicd environment list` | Inner **GET** list environments (path from `cicd_openapi.v2.json` discovery) |
-| `cicd environment get <environment-id>` | Inner **GET** one environment (path from `cicd_openapi.v2.json` discovery) |
-| `cicd environment create` | Inner **POST** create environment (path from `cicd_openapi.v2.json` discovery) |
-| `cicd repository list` | Inner **GET** list git repositories (path from `cicd_openapi.v2.json` discovery) |
-| `cicd repository get <repository-id>` | Inner **GET** one git repository (path from `cicd_openapi.v2.json` discovery) |
-| `cicd repository create` | Inner **POST** create git repository (path from `cicd_openapi.v2.json` discovery) |
-| `cicd repository ssh-key --repository-id <id>` | Inner **POST** generate SSH public key for a git repository (path from `cicd_openapi.v2.json` discovery) |
-| `cicd repository http-credentials --repository-id <id>` | Inner **PUT** update HTTP credentials for a git repository (path from `cicd_openapi.v2.json` discovery) |
-| `cicd repository validate --repository-id <id>` | Inner **POST** validate repository authentication (path from `cicd_openapi.v2.json` discovery) |
-| `cicd repository authenticate --repository-id <id>` | Browser GitLab OAuth login: local loopback + direct Front API `POST /agentia/v1/gitoauth/authorize`; human-oriented stdout (not JSON) |
-| `cicd pipeline list` | Inner **GET** list pipelines (path from `cicd_openapi.v2.json` discovery) |
-| `cicd pipeline get <pipeline-id>` | Inner **GET** one pipeline (path from `cicd_openapi.v2.json` discovery) |
-| `cicd pipeline create` | Inner **POST** create pipeline (path from `cicd_openapi.v2.json` discovery) |
-| `cicd pipeline update <pipeline-id>` | Inner **PATCH** update pipeline (path from `cicd_openapi.v2.json` discovery) |
-| `cicd pipeline delete <pipeline-id>` | Inner **DELETE** delete pipeline (path from `cicd_openapi.v2.json` discovery) |
-| `cicd pipeline visualize <pipeline-id> [--format ascii\|mermaid\|dot\|html] [--open]` | Render pipeline environment graph from live connections (ASCII default; `--open` writes HTML and opens browser) |
-| `cicd pipeline connection list [--pipeline-id <id>]` | Inner **GET** list pipeline connections (path from `cicd_openapi.v2.json` discovery) |
-| `cicd pipeline connection get <connection-id>` | Inner **GET** one pipeline connection (path from `cicd_openapi.v2.json` discovery) |
-| `cicd pipeline connection create` | Inner **POST** create pipeline connection (path from `cicd_openapi.v2.json` discovery) |
-| `cicd pipeline connection update <connection-id>` | Inner **PATCH** update pipeline connection (path from `cicd_openapi.v2.json` discovery) |
-| `cicd pipeline connection delete <connection-id>` | Inner **DELETE** delete pipeline connection (path from `cicd_openapi.v2.json` discovery) |
-| `plan work-item list [--pipeline-id <id>] [--release-id <id>]` | Inner **GET** list work items (path from `cicd_openapi.v2.json` discovery) |
-| `plan work-item get <work-item-id>` | Inner **GET** one work item (path from `cicd_openapi.v2.json` discovery) |
-| `plan work-item create` | Inner **POST** create work item (path from `cicd_openapi.v2.json` discovery) |
-| `plan work-item update <work-item-id>` | Inner **PATCH** update work item (path from `cicd_openapi.v2.json` discovery) |
-| `plan work-item delete <work-item-id>` | Inner **DELETE** delete work item (path from `cicd_openapi.v2.json` discovery) |
-| `cicd credential get <environment-id> <credential-id>` | Inner **GET** one environment credential (path from `cicd_openapi.v2.json` discovery) |
-| `cicd credential create <environment-id>` | Inner **POST** create environment credential (path from `cicd_openapi.v2.json` discovery) |
-| `cicd credential authenticate --env-id <id> --cred-id <id>` | Browser OAuth login: local loopback + **GET** auth-url; human-oriented stdout (not JSON) |
-| `cicd metadata index refresh --credential <id>` | Inner **POST** refresh Salesforce metadata index (full or partial by `--types`); optional `--module-type vlocity` adds `moduletype` to request body |
-| `cicd metadata index status <event-id>` | Inner **GET** metadata index refresh job status |
-| `cicd metadata index search --credential <id>` | Inner **POST** search Salesforce metadata index; optional `--module-type vlocity` adds `moduletype` to request body |
-| `cicd metadata types --environment <id> --credential <id>` | Inner **GET** metadata types in system (`/v2/release/metadata/types/{system_id}`); optional `--module-type vlocity` adds `moduleTypes=vlocity` |
-| `cicd metadata users --environment <id> --credential <id>` | Inner **GET** users on system (`/v2/release/metadata/users/{system_id}`); optional `--module-type vlocity` adds `moduleTypes=vlocity` |
-| `cicd deploy-selection` | Inner **POST** submit a Salesforce deploy selection job (`/v2/release/metadata/deploy-selection`) |
-| `cicd commit` | Inner **POST** submit a commit job (`/v2/release/actions/commit`) |
-| `user-story create` | If a matching create operation exists in `cicd_openapi.json`, call it; otherwise prints guidance and suggests `cicd invoke` |
+## Verify locally
 
-### Examples
+Unit coverage for MCP registration and redaction:
 
-**Ping (after login):**
-
-```bash
-agentia cicd ping
+```sh-session
+$ npm test -- --grep 'mcp'
 ```
 
-**Generic invoke — inner GET /health:**
-
-```bash
-agentia cicd invoke --endpoint /health --method GET --body '{}'
-```
+Live smoke check through Cursor: call `agentia_environment_list` or `agentia_project_default_get` after auth is configured. For pipeline and metadata tools, use Test14 IDs from your local `.env.integration`.
 
-**Generic invoke — inner POST /navigation/enabled** (same shape as deployer `CICDEnabledCallout`):
+# Commands
+<!-- commands -->
+* [`agentia help [COMMAND]`](#agentia-help-command)
+* [`agentia plugins`](#agentia-plugins)
+* [`agentia plugins add PLUGIN`](#agentia-plugins-add-plugin)
+* [`agentia plugins:inspect PLUGIN...`](#agentia-pluginsinspect-plugin)
+* [`agentia plugins install PLUGIN`](#agentia-plugins-install-plugin)
+* [`agentia plugins link PATH`](#agentia-plugins-link-path)
+* [`agentia plugins remove [PLUGIN]`](#agentia-plugins-remove-plugin)
+* [`agentia plugins reset`](#agentia-plugins-reset)
+* [`agentia plugins uninstall [PLUGIN]`](#agentia-plugins-uninstall-plugin)
+* [`agentia plugins unlink [PLUGIN]`](#agentia-plugins-unlink-plugin)
+* [`agentia plugins update`](#agentia-plugins-update)
 
-```bash
-agentia cicd invoke --endpoint /navigation/enabled --method POST \
-  --body '{"objectName":"Copado_User_Story__c","action":"merge"}'
-```
+## `agentia help [COMMAND]`
 
-**List environments (v2 corpus API):**
+Display help for agentia.
 
-```bash
-agentia cicd environment list
 ```
+USAGE
+  $ agentia help [COMMAND...] [-n]
 
-**Get one environment:**
-
-```bash
-agentia cicd environment get env-abc123
-```
+ARGUMENTS
+  [COMMAND...]  Command to show help for.
 
-**Create an environment:**
+FLAGS
+  -n, --nested-commands  Include all nested commands in the output.
 
-```bash
-agentia cicd environment create --name "Dev Sandbox" --type Sandbox
+DESCRIPTION
+  Display help for agentia.
 ```
 
-**List git repositories:**
+_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/6.2.53/src/commands/help.ts)_
 
-```bash
-agentia cicd repository list
-```
+## `agentia plugins`
 
-**Get one git repository:**
+List installed plugins.
 
-```bash
-agentia cicd repository get repo-abc123
 ```
+USAGE
+  $ agentia plugins [--json] [--core]
 
-**Create a git repository** (`--name` and `--provider` required; valid `--provider` values: `Github`, `Bitbucket`, `Gitlab`, `Microsoft Team Service`, `Copado Version Control`, `Others`; optional `--auth-type` (`HTTPS`, `SSH`, `OAuth`), `--uri`, `--tag-base-url`, `--pull-request-base-url`, `--commit-base-url`, `--branch-base-url`, or `--data`):
+FLAGS
+  --core  Show core plugins.
 
-```bash
-agentia cicd repository create --name "My Repo" --provider Github
-```
+GLOBAL FLAGS
+  --json  Format output as json.
 
-**Generate an SSH public key for a git repository** (`--repository-id` required; response `data` includes `publicKey` and `algorithm`):
+DESCRIPTION
+  List installed plugins.
 
-```bash
-agentia cicd repository ssh-key --repository-id repo-abc123
+EXAMPLES
+  $ agentia plugins
 ```
 
-**Update HTTP credentials for a git repository** (`--repository-id` required; `--username` and `--password` required unless supplied via `--data`; optional `--data <json>` merged with flags; flags win on conflict; returns `204` with no body on success):
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.84/src/commands/plugins/index.ts)_
 
-```bash
-agentia cicd repository http-credentials \
-  --repository-id repo-abc123 \
-  --username git-user \
-  --password git-pass
-```
+## `agentia plugins add PLUGIN`
 
-**Validate repository authentication** (`--repository-id` required; response `data` includes `validated` and optional `message`):
+Installs a plugin into agentia.
 
-```bash
-agentia cicd repository validate --repository-id repo-abc123
 ```
+USAGE
+  $ agentia plugins add PLUGIN... [--json] [-f] [-h] [-s | -v]
 
-**Authenticate a git repository** (GitLab OAuth via direct Front API; repository must exist with `authType=OAuth` and provider GitLab; optional `--port`, `--timeout` in seconds, default 300):
+ARGUMENTS
+  PLUGIN...  Plugin to install.
 
-```bash
-agentia cicd repository authenticate --repository-id 8f14e45f-ceea-467a-9575-2f7f5e6f1b0e
-```
+FLAGS
+  -f, --force    Force npm to fetch remote resources even if a local copy exists on disk.
+  -h, --help     Show CLI help.
+  -s, --silent   Silences npm output.
+  -v, --verbose  Show verbose npm output.
 
-On success, copado-front-api redirects the browser to the CLI loopback URL with `?status=success`. On failure, the redirect includes `?status=error&reason=...`. The CLI prints progress lines to stdout and exits `0` on success, `1` on auth failure, `130` on timeout. This command does **not** use the CICD gateway proxy or OpenAPI discovery.
+GLOBAL FLAGS
+  --json  Format output as json.
 
-**List pipelines:**
+DESCRIPTION
+  Installs a plugin into agentia.
 
-```bash
-agentia cicd pipeline list
-```
-
-**Get one pipeline:**
+  Uses npm to install plugins.
 
-```bash
-agentia cicd pipeline get pipe-abc123
-```
+  Installation of a user-installed plugin will override a core plugin.
 
-**Create a pipeline** (`--name`, `--status`, and `--repository-id` required; valid `--status` values: `active`, `paused`, `archived`; optional `--data <json>` merged with flags; flags win on conflict):
+  Use the AGENTIA_NPM_LOG_LEVEL environment variable to set the npm loglevel.
+  Use the AGENTIA_NPM_REGISTRY environment variable to set the npm registry.
 
-```bash
-agentia cicd pipeline create \
-  --name "Release Pipeline" \
-  --status active \
-  --repository-id repo-abc123
-```
+ALIASES
+  $ agentia plugins add
 
-**Update a pipeline** (at least one of `--name`, `--status`, `--repository-id`, or `--data` required):
+EXAMPLES
+  Install a plugin from npm registry.
 
-```bash
-agentia cicd pipeline update pipe-abc123 --status paused
-```
+    $ agentia plugins add myplugin
 
-**Delete a pipeline:**
+  Install a plugin from a github url.
 
-```bash
-agentia cicd pipeline delete pipe-abc123
-```
+    $ agentia plugins add https://github.com/someuser/someplugin
 
-**Visualize a pipeline** (fetches pipeline metadata and connections, renders environment graph; default ASCII in terminal):
+  Install a plugin from a github slug.
 
-```bash
-agentia cicd pipeline visualize pipe-abc123
-agentia cicd pipeline visualize pipe-abc123 --format mermaid
-agentia cicd pipeline visualize pipe-abc123 --format dot
-agentia cicd pipeline visualize pipe-abc123 --format html > pipeline.html
-agentia cicd pipeline visualize pipe-abc123 --open
+    $ agentia plugins add someuser/someplugin
 ```
 
-`--format` accepts `ascii` (default), `mermaid`, `dot`, or `html`. `--open` writes a temporary HTML file and opens it in the default browser (falls back to ASCII with a stderr warning in headless environments).
+## `agentia plugins:inspect PLUGIN...`
 
-**List pipeline connections** (optional `--pipeline-id` filter):
+Displays installation properties of a plugin.
 
-```bash
-agentia cicd pipeline connection list --pipeline-id pipe-abc123
 ```
+USAGE
+  $ agentia plugins inspect PLUGIN...
 
-**Get one pipeline connection:**
+ARGUMENTS
+  PLUGIN...  [default: .] Plugin to inspect.
 
-```bash
-agentia cicd pipeline connection get conn-abc123
-```
-
-**Create a pipeline connection** (`--pipeline-id`, `--from-environment-id`, and `--to-environment-id` required; optional `--source-branch-name`, `--destination-branch-name`, or `--data`):
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
 
-```bash
-agentia cicd pipeline connection create \
-  --pipeline-id pipe-abc123 \
-  --from-environment-id env-dev \
-  --to-environment-id env-staging \
-  --source-branch-name main \
-  --destination-branch-name release
-```
+GLOBAL FLAGS
+  --json  Format output as json.
 
-**Update a pipeline connection** (at least one update field required):
+DESCRIPTION
+  Displays installation properties of a plugin.
 
-```bash
-agentia cicd pipeline connection update conn-abc123 --destination-branch-name hotfix
+EXAMPLES
+  $ agentia plugins inspect myplugin
 ```
 
-**Delete a pipeline connection:**
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.84/src/commands/plugins/inspect.ts)_
 
-```bash
-agentia cicd pipeline connection delete conn-abc123
-```
+## `agentia plugins install PLUGIN`
 
-**List work items** (optional `--pipeline-id` and/or `--release-id` filters):
+Installs a plugin into agentia.
 
-```bash
-agentia plan work-item list --pipeline-id pipe-abc123 --release-id rel-abc123
 ```
+USAGE
+  $ agentia plugins install PLUGIN... [--json] [-f] [-h] [-s | -v]
 
-**Get one work item:**
+ARGUMENTS
+  PLUGIN...  Plugin to install.
 
-```bash
-agentia plan work-item get wi-abc123
-```
+FLAGS
+  -f, --force    Force npm to fetch remote resources even if a local copy exists on disk.
+  -h, --help     Show CLI help.
+  -s, --silent   Silences npm output.
+  -v, --verbose  Show verbose npm output.
 
-**Create a work item** (`--title` required; optional `--pipeline-id`, `--release-id`, `--current-environment-id`, `--branch-name`, or `--data`):
+GLOBAL FLAGS
+  --json  Format output as json.
 
-```bash
-agentia plan work-item create \
-  --title "Implement deployment checks" \
-  --pipeline-id pipe-abc123 \
-  --release-id rel-abc123 \
-  --current-environment-id env-dev123 \
-  --branch-name feature/US-12345-add-checks
-```
+DESCRIPTION
+  Installs a plugin into agentia.
 
-**Update a work item** (at least one update field required: `--title`, `--pipeline-id`, `--release-id`, `--current-environment-id`, `--branch-name`, or `--data`):
+  Uses npm to install plugins.
 
-```bash
-agentia plan work-item update wi-abc123 \
-  --current-environment-id env-qa456 \
-  --branch-name release/1.0
-```
+  Installation of a user-installed plugin will override a core plugin.
 
-**Delete a work item:**
+  Use the AGENTIA_NPM_LOG_LEVEL environment variable to set the npm loglevel.
+  Use the AGENTIA_NPM_REGISTRY environment variable to set the npm registry.
 
-```bash
-agentia plan work-item delete wi-abc123
-```
+ALIASES
+  $ agentia plugins add
 
-**Get one credential** (both ids required):
+EXAMPLES
+  Install a plugin from npm registry.
 
-```bash
-agentia cicd credential get env-abc123 cred-xyz789
-```
+    $ agentia plugins install myplugin
 
-**Create a credential** (`--name` required; optional `--default-credential`, `--username`, `--unique-id`, or `--data`):
+  Install a plugin from a github url.
 
-```bash
-agentia cicd credential create env-1 --name "Default Org User" --default-credential
-```
+    $ agentia plugins install https://github.com/someuser/someplugin
 
-**Authenticate a credential** (Step 3 — opens a browser for Salesforce OAuth; optional `--port`, `--timeout` in seconds, default 300):
+  Install a plugin from a github slug.
 
-```bash
-agentia cicd credential authenticate --env-id env-1 --cred-id cred-456
+    $ agentia plugins install someuser/someplugin
 ```
 
-On success, copado-front-api redirects the browser to the CLI loopback URL with **no** query parameters. On failure, the redirect includes `errorCode` and `errorDescription` (see `AgentiaOAuthErrorCodes` in copado-front-api). The CLI prints progress lines to stdout and exits `0` on success, `1` on auth failure, `130` on timeout.
-
-On Linux without `$DISPLAY` (SSH/headless), the CLI prints the auth URL instead of opening a browser and waits for Enter after you complete login elsewhere.
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.84/src/commands/plugins/install.ts)_
 
-There is no credential list API. To discover credential ids for an environment, use **`cicd environment get <environment-id>`** and read the `credentials` array in the response.
+## `agentia plugins link PATH`
 
-**Refresh Salesforce metadata index (full):**
+Links a plugin into the CLI for development.
 
-```bash
-agentia cicd metadata index refresh --credential cred-xyz789 --wait
 ```
+USAGE
+  $ agentia plugins link PATH [-h] [--install] [-v]
 
-**Partial refresh by metadata types:**
+ARGUMENTS
+  PATH  [default: .] path to plugin
 
-```bash
-agentia cicd metadata index refresh --credential cred-xyz789 --types ApexClass,Flow --wait --timeout 600
-```
+FLAGS
+  -h, --help          Show CLI help.
+  -v, --verbose
+      --[no-]install  Install dependencies after linking the plugin.
 
-**Vlocity metadata index refresh** (optional `--module-type vlocity` adds `moduletype: "vlocity"` to the request body):
+DESCRIPTION
+  Links a plugin into the CLI for development.
 
-```bash
-agentia cicd metadata index refresh --credential cred-xyz789 --module-type vlocity --wait
-```
-
-**Poll refresh status** (event id from the refresh response `data.eventId`):
+  Installation of a linked plugin will override a user-installed or core plugin.
 
-```bash
-agentia cicd metadata index status job-abc123
-```
+  e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
+  command will override the user-installed or core plugin implementation. This is useful for development work.
 
-**Search metadata index** (credential id from `cicd environment get` or `cicd credential get`; uses `credentialId`, not `sourceCredentialId`):
 
-```bash
-agentia cicd metadata index search \
-  --credential 669745f0-1477-4e70-ada0-4272b78c5617 \
-  --types ApexClass,ApexTrigger \
-  --source NewAndChanged \
-  --limit 100
+EXAMPLES
+  $ agentia plugins link myplugin
 ```
 
-**Search deleted metadata** (`--source` accepts `Deleted`, `deleted`, or `delete`; all map to `"source": "Deleted"` in the request body):
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.84/src/commands/plugins/link.ts)_
 
-```bash
-agentia cicd metadata index search \
-  --credential 669745f0-1477-4e70-ada0-4272b78c5617 \
-  --types ApexClass \
-  --source deleted
-```
+## `agentia plugins remove [PLUGIN]`
 
-**Search Vlocity metadata index** (optional `--module-type vlocity` adds `moduletype: "vlocity"` to the request body):
+Removes a plugin from the CLI.
 
-```bash
-agentia cicd metadata index search \
-  --credential 0409d7c4-ea05-4ca7-bb70-8e9d8022b8b8 \
-  --types ApexClass \
-  --module-type vlocity
 ```
+USAGE
+  $ agentia plugins remove [PLUGIN...] [-h] [-v]
 
-On V2, `NewAndChanged` is the default index search source. Use `--source Deleted` (or aliases `deleted` / `delete`) to search deleted metadata. `PreviouslyCommitted` may return `422` (`V2-MDT-005`) depending on backend support. If the index is empty or missing, run `metadata index refresh` first (a `404` with `V2-MDT-002` means no index exists yet).
-
-Omit `--wait` on refresh to return immediately after the job is submitted. With `--wait`, the CLI prints JSON status to stdout after each poll until the job reaches `COMPLETED` or `ERROR`. V2 refresh uses the credential’s Salesforce session and supports full index refresh (no `--types`) or partial refresh by metadata type names only.
+ARGUMENTS
+  [PLUGIN...]  plugin to uninstall
 
-**List metadata types in a system** (`--environment` is the system id; `--credential` is passed as the `credentialId` query param; optional `--module-type vlocity` adds `moduleTypes=vlocity`):
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
 
-```bash
-agentia cicd metadata types \
-  --environment env-abc123 \
-  --credential cred-xyz789
-```
+DESCRIPTION
+  Removes a plugin from the CLI.
 
-**List Vlocity metadata types in a system:**
+ALIASES
+  $ agentia plugins unlink
+  $ agentia plugins remove
 
-```bash
-agentia cicd metadata types \
-  --environment env-abc123 \
-  --credential cred-xyz789 \
-  --module-type vlocity
+EXAMPLES
+  $ agentia plugins remove myplugin
 ```
 
-**List users on a system** (`--environment` is the system id; `--credential` is passed as the `credentialId` query param; optional `--module-type vlocity` adds `moduleTypes=vlocity`):
+## `agentia plugins reset`
 
-```bash
-agentia cicd metadata users \
-  --environment env-abc123 \
-  --credential cred-xyz789
-```
-
-**List Vlocity users on a system:**
+Remove all user-installed and linked plugins.
 
-```bash
-agentia cicd metadata users \
-  --environment env-abc123 \
-  --credential cred-xyz789 \
-  --module-type vlocity
 ```
+USAGE
+  $ agentia plugins reset [--hard] [--reinstall]
 
-**Submit a deploy selection job** (`--source-credential` maps to `sourceId`, `--target-environment` to `destinationId`; metadata uses `Type:Member` syntax, repeatable):
-
-```bash
-agentia cicd deploy-selection \
-  --source-credential cred-src \
-  --target-environment env-dest \
-  --metadata ApexClass:MyClass \
-  --metadata Flow:My_Flow \
-  --dry-run \
-  --test-level NoTestRun
+FLAGS
+  --hard       Delete node_modules and package manager related files in addition to uninstalling plugins.
+  --reinstall  Reinstall all plugins after uninstalling.
 ```
 
-Optional flags: `--tests <class>` (repeatable; with `RunSpecifiedTests`), `--ignore-warnings`, `--rollback-on-error`, `--name <label>`, and `--data <json>` (merged with flags; flags win on conflict). `--dry-run` sets validation-only deployment (`isValidation: true`). Valid `--test-level` values: `NoTestRun`, `RunSpecifiedTests`, `RunLocalTests`, `RunAllTestsInOrg`.
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.84/src/commands/plugins/reset.ts)_
 
-On success, the response `data` includes fields such as `jobExecutionId`, `status`, and `resultId` (see `DeploySelectionResult` in `cicd_openapi.v2.json`).
+## `agentia plugins uninstall [PLUGIN]`
 
-**Submit a commit job** (metadata uses `Type:Name[:operation]` syntax, repeatable; default operation is `add`):
+Removes a plugin from the CLI.
 
-```bash
-agentia cicd commit \
-  --pipeline-id pipe-abc \
-  --work-item-id wi-123 \
-  --pipeline-connection-id conn-456 \
-  --message "US-12345: add MyClass" \
-  --metadata ApexClass:MyClass \
-  --metadata Flow:My_Flow:full
 ```
+USAGE
+  $ agentia plugins uninstall [PLUGIN...] [-h] [-v]
 
-Optional flags: `--do-not-push-changes` (skip pushing the feature branch; default is to push), `--recreate-if-exists`, `--clean-pull-request`, and `--data <json>` (merged with flags; flags win on conflict). Valid operation values: `add`, `retrieve_only`, `full`, `delete`, `selective_commit` (aliases such as `del`, `ret-only`, and `selectivecommit` are accepted).
+ARGUMENTS
+  [PLUGIN...]  plugin to uninstall
 
-On success, the response `data` includes fields such as `actionId`, `commitId`, `jobExecutionId`, and `status` (see `CommitResult` in `cicd_openapi.v2.json`).
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
 
-Successful list/get/create/credential-get/credential-create/repository-ssh-key/repository-http-credentials/repository-validate/metadata-types/metadata-users/deploy-selection/commit commands print JSON to stdout: `{ "status": <httpStatus>, "data": <inner payload> }`. Validation errors (`422`) print a message to stderr and exit with code 1. **`credential authenticate`** and **`repository authenticate`** use human-oriented messages, not JSON.
+DESCRIPTION
+  Removes a plugin from the CLI.
 
-**User story create** (only when the OpenAPI spec contains a discoverable “create user story” operation, for example tagged with `x-agentia-cli-command: user-story-create`):
+ALIASES
+  $ agentia plugins unlink
+  $ agentia plugins remove
 
-```bash
-agentia user-story create --data '{"your":"payload"}'
+EXAMPLES
+  $ agentia plugins uninstall myplugin
 ```
 
-If the spec does not define that operation yet, the command exits with an error and lists related paths; use **`cicd invoke`** with the inner route your team provides.
-
-## OpenAPI specs and CICD Gateway commands
-
-The CLI talks to the CICD Gateway **indirectly** through the Front API proxy (see [Front API CICD proxy](#front-api-cicd-proxy)). OpenAPI JSON files describe the **inner** gateway routes (`endpoint` + `method` + `body`). Named commands **discover** those routes from a bundled spec at runtime instead of hardcoding paths in TypeScript.
-
-### Two spec files (v1 and v2)
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.84/src/commands/plugins/uninstall.ts)_
 
-| Repo file | Bundled to | Typical API surface | Commands using it today |
-|-----------|------------|---------------------|-------------------------|
-| [`cicd_openapi.v2.json`](cicd_openapi.v2.json) | `dist/cicd_openapi.v2.json` | CICD Gateway v2 (environments, repositories, pipelines, …) | `cicd environment list`, `cicd environment get`, `cicd environment create`, `cicd credential get`, `cicd credential create`, `cicd credential authenticate`, `cicd metadata index refresh`, `cicd metadata index status`, `cicd metadata index search`, `cicd metadata types`, `cicd metadata users`, `cicd deploy-selection`, `cicd commit`, `cicd repository list`, `cicd repository get`, `cicd repository create`, `cicd repository ssh-key`, `cicd repository http-credentials`, `cicd repository validate`, `cicd pipeline list`, `cicd pipeline get`, `cicd pipeline create`, `cicd pipeline update`, `cicd pipeline delete`, `cicd pipeline connection list`, `cicd pipeline connection get`, `cicd pipeline connection create`, `cicd pipeline connection update`, `cicd pipeline connection delete`, `plan work-item list`, `plan work-item get`, `plan work-item create`, `plan work-item update`, `plan work-item delete` |
+## `agentia plugins unlink [PLUGIN]`
 
-On **`npm run build`**, `scripts/copy-openapi.mjs` copies both files into **`dist/`** next to the compiled JS. At runtime the CLI resolves paths via `resolveBundledOpenApiPath()` and `resolveBundledOpenApiV2Path()` in [`src/openapi.ts`](src/openapi.ts) — it does **not** read the repo-root copies unless you rebuild.
-
-**Refresh workflow:** update the root JSON from the gateway team → **`npm run build:openapi`** (or `codegen` + `build`) → commit specs and `src/generated/` → discovery and validation match on the next CLI run. See [Build → OpenAPI spec changes](#openapi-spec-changes-developer-workflow).
-
-### What uses OpenAPI vs what does not
-
-| Pattern | Examples | OpenAPI? |
-|---------|----------|----------|
-| **Discovery command** | `user-story create`, `cicd environment list/get/create`, `cicd credential get/create`, `cicd metadata index refresh/status/search`, `cicd metadata types/users`, `cicd deploy-selection`, `cicd commit`, `cicd repository list/get/create/ssh-key/http-credentials/validate`, `cicd pipeline list/get/create/update/delete`, `cicd pipeline connection list/get/create/update/delete`, `plan work-item list/get/create/update/delete` | Yes — load spec, find operation, call proxy |
-| **Orchestration command** | `cicd credential authenticate` | Uses auth-url from spec + local loopback (not JSON stdout) |
-| **Orchestration command (direct Front API)** | `cicd repository authenticate` | Direct `POST /agentia/v1/gitoauth/authorize` + local loopback (not JSON stdout; not OpenAPI/proxy) |
-| **Hardcoded shortcut** | `cicd ping` → `GET /health` | No |
-| **Manual escape hatch** | `cicd invoke --endpoint … --method … --body …` | No — caller supplies inner route |
-| **Non-gateway** | `login`, `hello` | No |
-
-Prefer **discovery commands** for stable, user-facing product verbs. Keep **`cicd invoke`** for one-offs, previews, or operations not yet wired as named commands.
-
-### Discovery flow (runtime)
-
-Every OpenAPI-bound command follows the same shape:
+Removes a plugin from the CLI.
 
 ```
-1. Resolve bundled spec path (v1 or v2 under dist/)
-2. loadOpenApiFromPath() — parse JSON paths/methods/components
-3. find*Operation(doc) — locate the inner route (tag or heuristics)
-4. Build inner request via schema bridge (flags + --data) for POST bodies
-5. Generated typescript-fetch client → proxy fetch adapter → callCicdGateway
-6. writeCicdSuccess / handleCicdFailure — stdout { status, data } or stderr on errors
-```
-
-**Codegen:** [`@openapitools/openapi-generator-cli`](https://openapi-generator.tech/) generates typed models and API clients under [`src/generated/`](src/generated/) (committed; see [`src/generated/README.md`](src/generated/README.md)). Regenerate with **`npm run codegen`** after spec changes. Generated clients never call the gateway directly; [`src/transport/proxy-fetch-adapter.ts`](src/transport/proxy-fetch-adapter.ts) routes every request through the Front API proxy. See [docs/architecture/cicd-openapi-codegen.md](docs/architecture/cicd-openapi-codegen.md) for the full architecture.
+USAGE
+  $ agentia plugins unlink [PLUGIN...] [-h] [-v]
 
-**Schema-driven CLI inputs:** For commands like `cicd environment create`, request validation and Commander flags are derived from OpenAPI `requestBody` schemas (`required`, property types, enums) via [`src/cli/schema-reader.ts`](src/cli/schema-reader.ts), [`src/cli/body-builder.ts`](src/cli/body-builder.ts), and [`src/cli/flag-mapper.ts`](src/cli/flag-mapper.ts) — not hand-maintained body builders.
+ARGUMENTS
+  [PLUGIN...]  plugin to uninstall
 
-Reference implementations:
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
 
-- **v1 POST + body:** [`src/cmd/user-story.ts`](src/cmd/user-story.ts) + schema bridge + [`runOpenApiCreateWithBridge`](src/cli/openapi-command.ts)
-- **v2 environment commands:** [`src/cmd/cicd-environment.ts`](src/cmd/cicd-environment.ts) + generated [`CorpusEnvironmentsCredentialsV2Api`](src/generated/cicd-v2/apis/CorpusEnvironmentsCredentialsV2Api.ts)
-- **v2 repository commands:** [`src/cmd/cicd-repository.ts`](src/cmd/cicd-repository.ts) + generated [`CorpusRepositoriesApi`](src/generated/cicd-v2/apis/CorpusRepositoriesApi.ts)
-- **v2 pipeline commands:** [`src/cmd/cicd-pipeline.ts`](src/cmd/cicd-pipeline.ts) + generated [`CorpusPipelinesApi`](src/generated/cicd-v2/apis/CorpusPipelinesApi.ts)
-- **v2 pipeline connection commands:** [`src/cmd/cicd-pipeline-connection.ts`](src/cmd/cicd-pipeline-connection.ts) + generated [`CorpusPipelineConnectionsApi`](src/generated/cicd-v2/apis/CorpusPipelineConnectionsApi.ts)
-- **v2 plan work item commands:** [`src/cmd/plan-work-item.ts`](src/cmd/plan-work-item.ts) + generated [`PlanWorkItemsApi`](src/generated/cicd-v2/apis/PlanWorkItemsApi.ts)
-- **v2 deploy selection:** [`src/cmd/cicd-deploy-selection.ts`](src/cmd/cicd-deploy-selection.ts) + [`src/cicd/deploy-selection.ts`](src/cicd/deploy-selection.ts) + [`runGeneratedDeploySelection`](src/cli/openapi-command.ts)
-- **v2 commit:** [`src/cmd/cicd-commit.ts`](src/cmd/cicd-commit.ts) + [`src/cicd/commit-request.ts`](src/cicd/commit-request.ts) + [`runGeneratedCommit`](src/cli/openapi-command.ts)
+DESCRIPTION
+  Removes a plugin from the CLI.
 
-Shared transport and response handling live in [`src/cicd-client.ts`](src/cicd-client.ts) and [`src/transport/invoke-generated.ts`](src/transport/invoke-generated.ts).
+ALIASES
+  $ agentia plugins unlink
+  $ agentia plugins remove
 
-### How an operation is found
+EXAMPLES
+  $ agentia plugins unlink myplugin
+```
 
-Discovery scans `paths` in the spec. For each candidate operation it checks, in order:
+## `agentia plugins update`
 
-1. **Extension tag (preferred)** — `x-agentia-cli-command` on the operation object:
-   - `user-story-create` → `user-story create`
-   - `environment-list` / `environment-get` / `environment-create` → `cicd environment list` / `get` / `create`
-   - `repository-list` / `repository-get` / `repository-create` → `cicd repository list` / `get` / `create`
-   - `repository-ssh-key` / `repository-http-credentials` / `repository-validate` → `cicd repository ssh-key` / `http-credentials` / `validate`
-   - `pipeline-list` / `pipeline-get` / `pipeline-create` / `pipeline-update` / `pipeline-delete` → `cicd pipeline list` / `get` / `create` / `update` / `delete`
-   - `pipeline-connection-list` / `pipeline-connection-get` / `pipeline-connection-create` / `pipeline-connection-update` / `pipeline-connection-delete` → `cicd pipeline connection list` / `get` / `create` / `update` / `delete`
-   - `work-item-list` / `work-item-get` / `work-item-create` / `work-item-update` / `work-item-delete` → `plan work-item list` / `get` / `create` / `update` / `delete`
-   - `deploy-selection` → `cicd deploy-selection`
-   - `commit` → `cicd commit`
-2. **Heuristics** — `operationId` / `summary` keywords (e.g. “list” + “environment”)
-3. **Path pattern** — e.g. `/v2/corpus/environments/` for list, `/v2/corpus/environments/{environment_id}` for get, `/v2/release/metadata/deploy-selection` for deploy selection, `/v2/release/actions/commit` for commit
+Update installed plugins.
 
-If multiple operations match, the tagged one wins. If none match, the command prints related paths from the spec and suggests **`cicd invoke`**.
+```
+USAGE
+  $ agentia plugins update [-h] [-v]
 
-**Gateway/API owners:** when adding a new CLI-bound operation, add the tag to the OpenAPI export:
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
 
-```json
-"get": {
-  "operationId": "list_environments_corpus_environments__get",
-  "summary": "List Environments",
-  "x-agentia-cli-command": "environment-list"
-}
+DESCRIPTION
+  Update installed plugins.
 ```
 
-### Adding a new CICD Gateway command (checklist)
-
-1. **Choose the spec** — v1 (`cicd_openapi.json`) or v2 (`cicd_openapi.v2.json`) depending on which gateway surface the route lives on.
-2. **Ensure the operation exists** in the spec (or land the spec update first). Tag it with `x-agentia-cli-command: <your-command-id>`.
-3. **Add discovery** in [`src/openapi.ts`](src/openapi.ts):
-   - `findYourOperation(doc)` returning `{ path, method, operation } | null`
-   - optional `listYourRelatedPaths(doc)` for error hints
-4. **Add a command module** under [`src/cmd/`](src/cmd/):
-   - load bundled spec (`resolveBundledOpenApiPath()` or `resolveBundledOpenApiV2Path()`)
-   - call your `find*Operation`
-   - substitute path params with [`substitutePathParams`](src/openapi.ts) / [`primaryPathParamName`](src/openapi.ts) when needed
-   - use `callCicdGateway` or `executeCicdGet` / `executeCicdPost` / shared success-failure helpers
-5. **Register** the command in [`src/cli.ts`](src/cli.ts) or from [`src/cmd/cicd.ts`](src/cmd/cicd.ts) (nested under `cicd` when appropriate).
-6. **Tests** in `test/`:
-   - discovery unit tests against bundled spec or minimal mock docs ([`test/openapi.test.js`](test/openapi.test.js))
-   - command tests with mock `fetchImpl` ([`test/cicd-environment.test.js`](test/cicd-environment.test.js))
-7. **Document** the command in the [Commands (summary)](#commands-summary) table and examples above.
-
-### Output and error conventions
-
-Discovery commands should align with existing CICD helpers:
-
-- **Success:** stdout JSON `{ "status": <httpStatus>, "data": <inner payload> }` (via `writeCicdSuccess`)
-- **Gateway validation (`422`):** stderr with `message` and optional `(code: …)` (via `handleCicdFailure`)
-- **Other HTTP errors:** stderr with message or response text; `process.exitCode = 1`
-- **Missing spec file:** stderr pointing at `dist/cicd_openapi*.json` and `npm run build`
-- **Missing operation:** stderr listing related paths + suggest `cicd invoke`
-
-Do not log secrets beyond existing profile/header behavior.
-
-### What OpenAPI is not used for (today)
-
-The bundled specs are **routing catalogs**, not full client generators. The CLI does **not**:
-
-- validate request/response bodies against JSON Schema at runtime
-- auto-generate Commander flags from parameters
-- register every operation as its own subcommand
-
-For ad-hoc access to any inner route, use **`cicd invoke`**. For new product commands, extend discovery as above.
-
-## How to develop
-
-### Watch mode
-
-```bash
-npm run dev
-```
-
-Keep this running in one terminal; run `node dist/cli.js …` in another after each compile. After pulling OpenAPI spec changes, run **`npm run build:openapi`** (or `codegen` then `build`). Watch mode alone does not copy specs to `dist/` or run codegen.
-
-### Tests
-
-```bash
-npm test
-```
-
-Runs `node --test` against `test/` (after a fresh build).
-
-### Project layout
-
-```
-agentia-cli/
-├── cicd_openapi.json     # CICD Gateway OpenAPI v1 (copied to dist on build)
-├── cicd_openapi.v2.json  # CICD Gateway OpenAPI v2 corpus (copied to dist on build)
-├── package.json
-├── tsconfig.json
-├── scripts/
-│   ├── codegen.mjs       # OpenAPI → src/generated/ (runs on build)
-│   └── copy-openapi.mjs  # repo-root specs → dist/
-├── src/
-│   ├── generated/        # OpenAPI Generator output (committed; do not edit)
-│   ├── cli.ts            # Entry and Commander wiring
-│   ├── config.ts         # Profiles and config file I/O
-│   ├── region.ts         # NA/NA2/EU/CUSTOM → Front API base URL
-│   ├── auth/
-│   │   └── frontApiHeaders.ts  # token2 vs PAT Front API headers
-│   ├── crt/
-│   │   ├── region.ts     # QA/US/AU/EU/SG → Platform base URL
-│   │   └── auth/         # PAT validation (Platform GET /users/me)
-│   ├── cicd-client.ts    # POST /json/v1/cicd-api; shared success/error helpers
-│   ├── cicd/
-│   │   ├── credential-authenticate.ts
-│   │   ├── repository-authenticate.ts  # GitLab OAuth via direct Front API
-│   │   ├── deploy-selection.ts  # Deploy selection request builder
-│   │   └── commit-request.ts  # Commit request builder
-│   ├── openapi.ts        # Load bundled specs; find*Operation discovery
-│   ├── cmd/
-│   │   ├── login.ts      # login token2, login pat
-│   │   ├── cicd.ts
-│   │   ├── cicd-environment.ts
-│   │   ├── cicd-repository.ts
-│   │   ├── cicd-deploy-selection.ts
-│   │   ├── cicd-commit.ts
-│   │   └── user-story.ts
-│   └── util/
-│       └── commander.ts
-├── test/
-│   ├── cicd-client.test.js
-│   ├── cicd-environment.test.js
-│   ├── cicd-repository.test.js
-│   ├── repository-authenticate.test.js
-│   ├── login-pat.test.js
-│   ├── openapi.test.js
-│   └── proxy-contract.test.js
-└── dist/                 # build output
-```
-
-## License / distribution
-
-The package is marked `"private": true` in `package.json`; publishing and licensing are defined by your Copado release process, not by this README.
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/5.4.84/src/commands/plugins/update.ts)_
+<!-- commandsstop -->