circleci-cli — Codex skill: what it does, how to install
Operates and troubleshoots CircleCI pipelines via the CircleCI CLI. Useful for validating configs, checking build failures, and triggering jobs directly from Codex.
npx skills add openai/plugins --skill circleci-cli
npx skills add openai/plugins --skill cli -a codexWhat circleci-cli does
This skill guides the agent through working with the circleci terminal tool. It prioritizes read-only inspection first, identifying failed steps and checking pipeline or trigger states before touching anything. Local CircleCI configuration files get validated before risky edits are committed.
When changes are required, the skill performs targeted reruns of specific jobs or triggers pipelines with explicit parameters. Guardrails stop the assistant from printing tokens or environment variable secrets in conversation. It also avoids obsolete commands like circleci api, relying on circleci help to verify available subcommands.
You need a locally installed circleci CLI, an active token, and organization permissions. Install this if you want to inspect and debug CircleCI runs without leaving your editor.
What it helps with
- inspect pipeline and workflow status to locate failing steps
- validate CircleCI configuration locally before committing
- rerun a failed workflow or specific job
- trigger new pipelines with branch context and custom parameters
Example prompts for the agent
- Inspect the latest pipeline run for this branch and find what failed
- Validate our CircleCI config locally
- Rerun the failed job in the current workflow
How to install circleci-cli
1Skills CLI (Vercel)
npx skills add openai/plugins --skill circleci-clinpx skills add openai/plugins --skill cli -a codex2Manually: put the files in place
.agents/skills/cli/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add openai/plugins --skill cli -a claude-code2Manually: put the files in place
~/.claude/skills/cli/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/cli/
Manually: put the files in place
.cursor/skills/cli/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install openai/plugins cli2Manually: put the files in place
.github/skills/cli/SKILL.mdPlatform CLI
gemini skills install https://github.com/openai/plugins --path plugins/circleci/skills/cliManually: put the files in place
.devin/skills/cli/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
From the same set201
The whole set →Similar
Questions about circleci-cli
How to install circleci-cli in Codex?
Run npx skills add openai/plugins --skill circleci-cli. Alternatively, place the skill definition in .agents/skills/cli/SKILL.md.
What does circleci-cli do?
It provides diagnostic workflows and operational commands for CircleCI. The agent checks CLI auth, inspects pipeline errors, validates YAML configurations, and triggers reruns.
What are the prerequisites for this skill?
You need the circleci CLI installed on your machine along with a valid authentication token. Organization permissions and a project slug or repository path are also required.
Source text
SKILL.md · MIT
--- name: circleci-cli description: Operate and troubleshoot CircleCI using the CircleCI CLI. Use when users ask to authenticate CLI access, inspect pipeline/workflow/job status, validate configuration locally, rerun pipelines/jobs, trigger pipelines, or gather actionable diagnostics from CLI outputs. --- # CircleCI CLI ## Overview Use this skill when the fastest path is CircleCI CLI-driven operations rather than editing config first. Prioritize safe, read-first diagnostics, then run targeted mutating commands only after confirming scope. ## Inputs To Gather - Repository path and target branch - CircleCI project slug (if needed) - Whether objective is inspect, rerun, trigger, or validate - Required token/auth state and org permissions ## Workflow 1. Verify CLI and auth state. - Confirm `circleci` is installed and version is available. - Confirm token/auth before issuing remote CircleCI commands. 2. Run read-only diagnostics first. - Inspect available pipeline/project/trigger state and capture concrete identifiers. - Extract first failing scope and step details from supported command output before rerun/trigger actions. 3. Validate config locally when relevant. - Run config validation/processing commands before committing risky edits. 4. Run targeted mutation commands. - Rerun only required workflow/job scope. - Trigger pipelines with explicit parameters and branch context. 5. Report results and next action. - Provide exact command results, remaining blockers, and safest follow-up. ## Guardrails - Prefer read-only commands before rerun/trigger/cancel operations. - Confirm organization/project scope before mutating pipeline state. - Never print raw secret values from environment variables or tokens. - If permissions fail, report exact auth/scope gap and safest remediation. - Respect installed CLI capabilities and avoid inventing commands. - Do not use `circleci api`, `circleci workflow`, or other unavailable legacy commands unless `circleci help` confirms they exist. ## Installed CLI Compatibility For newer `circleci` builds that expose domain subcommands (for example `pipeline`, `project`, `trigger`) but not `api`: - Verify available commands first with `circleci help`. - Use only discovered subcommands from help output. - Prefer `circleci pipeline list|create|run` and `circleci trigger ...` for pipeline operations. - For cloud job logs, use supported platform tools (CircleCI app/UI or connected CircleCI MCP tooling) if the CLI does not expose a logs command. ## Output Contract Provide: 1. Commands run and purpose. 2. Key outputs (pipeline/workflow/job ids, status, failing step). 3. Actions taken (rerun/trigger/validate) and why. 4. Remaining blockers and next recommended CLI command.
© CircleCI · MIT · openai/plugins
