@copado/agentia-cli

Command-line interface for Agentia headless Copado workflows (auth, environments, jobs, pipelines, metadata, and local MCP).

• @copado/agentia-cli
• Usage
• Local MCP Server
• Local Quality Gates
• License
• Commands

Usage

$ npm install -g @copado/agentia-cli@latest --registry https://registry.npmjs.org --@copado:registry=https://registry.npmjs.org
$ agentia COMMAND
running command...
$ agentia (--version)
@copado/agentia-cli/1.6.0 linux-x64 node-v22.23.4
$ agentia --help [COMMAND]
USAGE
  $ agentia COMMAND
...

Agentia checks npm rc and latest in the background and warns when a newer release is available for the installed version. Auto-selection uses an optional updateChannel preference in ~/.config/agentia-cli/config.json (rc keeps dual-channel compare and still installs a SemVer-greater stable; latest is stable-only). With no preference, prerelease installs compare both tags and pick the highest newer SemVer, while stable installs compare only latest. Run agentia update to install the selected release (an interactive RC-to-stable crossing can prompt once to save a preference; after a successful install it warns to run setup skills update in each project that uses Agentia-managed skills), agentia update --check to check without changing the installation or preference, or agentia update --channel rc|latest to force a channel and save that preference on install. RC is the supported prerelease channel; stable publications use npm's latest dist-tag.

Store gateway credentials before calling gateway-backed commands:

$ agentia auth set --cicd <api-key> --region na
$ agentia auth get

Using Agentia behind a proxy

Agentia honors the standard proxy environment variables on every outbound HTTP(S) request and on CRT browser WebSocket connections, similar to Salesforce CLI:

• HTTPS_PROXY / https_proxy for TLS traffic (recommended)
• HTTP_PROXY / http_proxy for plain HTTP
• NO_PROXY / no_proxy for hosts that must connect directly (comma-separated; supports * suffix wildcards)
• npm-style npm_config_https_proxy, npm_config_proxy, and npm_config_no_proxy when the CLI runs under npm

Loopback targets (localhost, 127.0.0.1, ::1) always bypass the proxy so local gateway development and IDE listeners stay direct.

$ export HTTPS_PROXY=http://proxy.example.com:3128
$ export NO_PROXY=localhost,127.0.0.1,.mycompany.com
$ agentia cicd project list

Corporate TLS inspection may require trusting your organization CA. Set NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem, or use NODE_USE_SYSTEM_CA=1 on supported Node versions.

For Cursor or Claude Code MCP, pass the same variables in the MCP server env block so gateway tools inherit them.

NTLM or Kerberos proxy authentication is not built in; use a local forwarding proxy such as px or cntlm that presents a plain HTTP proxy to Agentia.

Read a user story

agentia cicd work get <id> --json returns the complete user-story record supplied by the CICD gateway in the result property. The JSON response preserves nested related epic and feature records; human output presents the same field groups while redacting oauthSignature. Pass --user-stories-ahead-behind to also compare how many user stories are ahead of and behind the next pipeline environment when the story has a pipeline and source environment.

$ agentia cicd work get US-0001 --json
$ agentia cicd work get US-0001 --user-stories-ahead-behind

{
  "result": {
    "id": "a1Y000000000001EAA",
    "name": "US-0001",
    "title": "Improve deployment validation",
    "status": "Development In Progress",
    "project": "a0w000000000001AAA",
    "projectName": "Example Project",
    "pipelineId": "a0M000000000001EAA",
    "sourceEnvironment": "a0S000000000001EAA",
    "baseBranch": "main",
    "epic": {"id": "a0E000000000001EAA", "name": "EPIC-1", "title": "Example epic"},
    "feature": {"id": "aDs000000000001EAA", "title": "Example feature"}
  },
  "status": 0,
  "transactionId": "..."
}

cicd work create and cicd work update validate --acceptance-criteria locally: it must contain fewer than 255 characters.

For Copado AI agents, store the AI PAT and organization context once, then use ask for scripts or chat for an interactive session:

$ agentia auth set --ai <pat-token> --ai-domain robotic.copado.com --ai-org 42888
$ agentia ai agent ask --agent plan -p "Break this requirement into implementation steps"
$ agentia ai agent ask --agent knowledge -p "Summarize the available workspace guidance"
$ agentia ai agent chat --agent build --sf-org test14 --user-story US-1042

Interactive Help and Command History

Users can open an experimental, multi-turn Copado support conversation directly in an interactive terminal without an eager CICD credential check:

$ agentia help-agent
$ agentia support
$ agentia help --agent

Inside the chat, Enter submits the prompt and Shift+Enter inserts a new line.

Help Agent requests fresh short-lived access through the CICD gateway for every turn, so an invalid or missing CICD credential fails the question rather than preventing the chat from opening. Every request adds a CLI system message that identifies the assistant as a concise Copado expert on Agentia Headless and Copado tools for developers working locally. Response tokens are written as they arrive. On every turn the CLI refreshes version, platform, architecture, workspace basename, normalized current origin, dominant CLI/IDE/MCP usage counts, and the three newest sanitized command summaries. When tooling or a local-versus-cloud operations flow cannot be determined, the system prompt asks one brief clarifying question. Each command summary can contain command ID, normalized origin, parameters, timestamp, duration, status, exit code, CLI version, workspace basename, redacted structured result, and only the final 20 combined output lines. Follow-up turns also include a deterministic redacted digest of at most six successful prior messages, with fixed per-message and total byte limits instead of resending unbounded chat history. It never sends full 20 KiB logs, raw User-Agent headers, full paths, credentials, tokens, session IDs, request bodies, or arbitrary unredacted errors.

Agentia keeps at most 100 sanitized execution summaries in owner-private temporary storage. New records identify their source as cli, ide, or mcp; legacy records can omit it. CLI and IDE records can include redacted parameters, structured result data, and one ordered stream-tagged log that retains the last 20 KiB independently for stdout and stderr. MCP records contain only command ID, timing, outcome, CLI version, workspace basename, and origin—never arguments, output, results, or errors.

Successful Help Agent turn pairs are also stored, after redaction and 4 KiB per-message truncation, in owner-private temporary JSONL. This storage is not restored into later conversations, retains at most 100 pairs, and applies a rolling 24-hour expiry on access. Inspect command summaries or clear both stores with:

$ agentia history list --limit 10
$ agentia history list --limit 10 --json
$ agentia history clear --yes

Inside Help Agent, /clear resets only the in-memory conversation. agentia history clear --yes deletes both temporary history files. Runtime/history commands, interactive AI chat commands, and Help Agent entry points remain excluded from command-execution history; MCP calls add metadata-only usage entries. No MCP Help Agent or history-reading tool is provided.

See Interactive AI Help Agent for prerequisites, privacy details, limitations, and troubleshooting.

Agent Skills Setup

agentia setup skills create installs portable Markdown-only Agent Skills that teach compatible agents how to use Agentia CICD (including metadata exploration), CRT Testing, AI, and Pipelines Advanced commands correctly, plus target-specific routing artifacts (.agents/skills/agentia/SKILL.md, .cursor/rules/agentia.mdc, or .claude/skills/agentia/SKILL.md). Use --target agents for .agents/skills (portable default), --target cursor for .cursor/skills, or --target claude for .claude/skills. Setup does not modify customer root AGENTS.md.

$ agentia setup skills create --target agents
$ agentia setup skills create --cicd --target cursor --no-prompt
$ agentia setup skills update --ai --target agents --no-prompt

Use update to refresh Agentia-managed skill files. Unrelated files are preserved, and existing files without the Agentia managed marker are not overwritten unless --force is explicit.

Plugin skills

An installed plugin can contribute skills through an agentia:contribute hook (see plugin-sdk/README.md). They are third-party prompts, so none are installed by default and the hook runs only when you ask for plugin skills: interactive setup skills create, --plugin, setup skills list, or setup skills update when plugin skills are already installed. Interactive setup skills create lists what plugins contribute (nothing ticked) and installs only the ones you select; headless runs and --json install them only with --plugin:

$ agentia setup skills list
$ agentia setup skills create            # pick plugin skills in the prompt
$ agentia setup skills create --plugin @acme/agentia-plugin-release --target cursor --no-prompt
$ agentia setup skills update

A contributed skill with id release installs as agentia-release. setup skills list shows installable skills and why an invalid one is skipped; one failing or slow plugin never blocks the others, and a plugin without the hook is ignored. With --plugin and no pack flag only plugin skills are written; otherwise the generated Agentia rules file gets a "Plugin skills" line for each installed plugin skill. Plugin skills carry a per-plugin managed marker; files that are unmanaged or owned by another plugin are never replaced without --force. setup skills update with no flags also refreshes plugin skills already in the project, and warns when their plugin is uninstalled or no longer contributes them. Nothing is deleted unless you run agentia setup skills update --prune, which removes only the files that carry that plugin's managed marker (never unmarked files, symlinks, or other plugins' files), drops their line from the rules file, and is skipped for any plugin whose hook failed or timed out. Contributions are rejected if they list non-Markdown files, symbolic links, paths outside the plugin, allowed-tools, a reserved or duplicate id, an unsupported apiVersion, or exceed 50 files, 256 KiB per file, or 1 MiB per skill.

Contributor setup, local gateway mode, and integration testing are documented in DEVELOPMENT.md.

Local MCP Server

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.

Prerequisites

1. Install the CLI so agentia is available:

$ npm install -g @copado/agentia-cli@rc --registry https://registry.npmjs.org --@copado:registry=https://registry.npmjs.org

2. Store credentials. The MCP server reuses the same keychain-backed auth as the CLI:

$ agentia auth set --cicd <api-key> --region na
$ agentia auth set --ai <pat-token> --ai-domain robotic.copado.com --ai-org 42888
$ agentia auth get

3. Confirm the MCP command is available:

$ agentia mcp --help
$ agentia mcp start --help

Start the server

$ agentia mcp start

This command is long-running. It speaks MCP over stdio and waits for a client connection. Do not expect interactive terminal output after start.

Configure Cursor

Add an MCP server entry that launches Agentia:

{
  "mcpServers": {
    "agentia": {
      "type": "stdio",
      "command": "agentia",
      "args": ["mcp", "start"],
      "env": {
        "AGENTIA_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

This works in either .cursor/mcp.json or global ~/.cursor/mcp.json: Cursor expands ${workspaceFolder} for the active workspace, so Agentia loads that repository's .agentia defaults, project auth, and .env. After saving the config, reload MCP servers in Cursor.

Configure Claude Code

agentia setup can write the project .mcp.json entry for Claude Code and pre-approve the agentia server in .claude/settings.local.json. The recommended entry passes Claude's project directory through to Agentia:

{
  "mcpServers": {
    "agentia": {
      "type": "stdio",
      "command": "agentia",
      "args": ["mcp", "start"],
      "env": {
        "AGENTIA_PROJECT_ROOT": "${CLAUDE_PROJECT_DIR:-}"
      }
    }
  }
}

Claude Code expands CLAUDE_PROJECT_DIR for local stdio servers. If AGENTIA_PROJECT_ROOT or CLAUDE_PROJECT_DIR is empty or still an unexpanded placeholder (for example ${CLAUDE_PROJECT_DIR:-}), Agentia ignores it and falls back to the MCP client's reported folder, then walks upward for project markers.

You can also add Agentia manually with claude mcp add or an mcpServers entry in ~/.claude.json.

For other local MCP clients, set AGENTIA_PROJECT_ROOT to an absolute project directory. When no explicit root exists, Agentia uses one local MCP root when available, otherwise searches upward from its startup directory. Multiple local roots require AGENTIA_PROJECT_ROOT to avoid selecting the wrong project.

Optional definitive override: set AGENTIA_MCP_PROJECT_ROOT to an absolute project directory in the MCP server env. When set, Agentia uses that path as the project root for defaults, auth profiles, and .env loading, and does not use the client's roots/list result for project selection.

Request identity

Gateway requests identify what ran in Referer and how it ran in User-Agent and event-source.

• Shell CLI: Referer is the oclif command id (for example cicd:environment:list). User-Agent is agentia-cli/<version> and event-source is agentia-cli.
• MCP: tools that wrap a CLI command send that same command id as Referer. User-Agent is agentia-mcp/<version> and event-source is agentia-mcp. MCP-only helpers keep their MCP tool id as Referer.
• IDE: set AGENTIA_CLIENT_ORIGIN=ide when the IDE extension spawns Agentia, including agentia mcp start, and pass the extension version as AGENTIA_IDE_VERSION. A valid IDE version produces User-Agent: agentia-ide/<ide-version> (agentia-cli/<cli-version>); missing or invalid values fall back to agentia-ide/<cli-version>. event-source remains agentia-ide. Unsupported origin values and IDE versions are ignored.

Available tools

Tools are JSON-safe and return structured results. Sensitive fields are redacted.

Notes for common tools

• agentia_work_set, agentia_work_publish, and agentia_work_submit operate on the Git repository in the MCP server process's current working directory. They can check out a branch, fetch from, and push to origin; start the server from the intended repository. If agentia_work_set returns status: "warning", it printed the gateway message and did not run git or update local work context. Work set fetches the base branch and, when that ref exists, the remote feature branch, then creates or checks out feature/<user-story-name> from the remote feature when present, otherwise from the base. Work set also compares the Copado Story source credential with the CICD project default after the work/set response: it warns when the Story credential is missing, skips comparison when a bound Story has no project default, and warns without changing the Story when they differ (current credential and environment are shown; use agentia_work_update / cicd work update --source-credential to change it).
• agentia_ai_ask mirrors agentia ai agent ask --json: it buffers the agent response, returns structured warnings/followups/links, and never returns hidden reasoning chunks. Plan, Build, and Test requests accept credentialId, forceCredentialSync, and noCredentialSync to control project-default Copado credential synchronization, plus sfOrg only as prompt context.
• Browser-based cicd environment auth web login remains a CLI-only command.
• Pipeline and job tools require userId and organizationId for the gateway x-user-id and x-organization-id headers.
• Job list accepts optional filters such as status, name, type, parent, context, and limit.
• Metadata tools require the same gateway identifiers as the CLI flags, for example pipelineId, sourceOrgId, and sourceCredentialId where applicable.
• Project list accepts optional mine to restrict results to projects owned by or related to the current user.
• Project default tools read and write local or global defaults managed by agentia cicd project default *.
• User get defaults id to me for the authenticated user.
• Environment create/update tools mirror the corresponding CLI commands and only send fields you provide.
• Work set/publish/submit/done tools mirror the CLI workflow: set prepares feature/<user-story-name>, then publish / submit / done operate on the current feature branch with the same clean-tree and base-branch requirements. agentia_work_push remains a compatibility alias of agentia_work_publish.
• agentia_cloud_commit requires metadataCategory for simple input, and each changes entry requires c (or category). For Salesforce metadata set SFDX. Copado SFDX deploy classifies changeset rows by that field; omitting it logs "Salesforce changes not found." and skips the deploy.
• Work deployment-step tools mirror cicd work deployment-step *; create accepts either the resolved inner configJson or the same type-specific guided fields as the CLI, update uses null to clear nullable fields, and reorder requires complete before and after ID arrays.
• Promotion list accepts the same filters as agentia cicd promotion list; promotion get takes a Promotion ID. agentia_promotion_job_step_update mirrors cicd promotion job-step update, validates sparse manual-task updates, and trims assignee values. agentia_promotion_run and agentia_cloud_promote reuse the CLI preflight, run/resume, ordered deployment-step, and bounded polling behavior. agentia_cloud_promote also auto-creates a forward Draft promotion when none contains the User Story and returns optional createdPromotion in the result.
• agentia_notification_configure mirrors agentia cicd notification configure: Slack-only subscriptions on a pipeline for the current user. Resolve the pipeline Id with agentia_pipeline_get first. All fields are required (pipelineId, event, destinationType, destinationId, subscription). Event names with spaces use the same underscore tokens as the CLI (for example Test_Not Started).
• agentia_notification_get mirrors agentia cicd notification get: requires pipelineId and returns sanitized { pipelineId, subscriptions } for the authenticated user (no raw system-property metadata).

CRT Git-backed jobs

Use Git storage when CRT should fetch Robot Framework files from a repository branch instead of uploading local files into a snapshot job.

agentia testing job create \
  --project 112901 \
  --robot 123456 \
  --name "Login smoke from Git" \
  --git-url https://github.com/acme/crt-tests.git \
  --git-branch feature/login-smoke

For private repositories, prefer a CRT domain credential:

agentia testing job create \
  --project 112901 \
  --robot 123456 \
  --name "Login smoke from Git" \
  --git-url http