Can I use CircleCI as a CLI?

Yes. KosmoKrator exposes a CircleCI CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose CircleCI through MCP?

Yes. The KosmoKrator MCP gateway can expose selected CircleCI tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are CircleCI credentials stored?

CircleCI credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for CircleCI MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

CircleCI Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the CircleCI KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.circleci.*. Use lua_read_doc("integrations.circleci") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic CircleCI workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.circleci.api_delete({}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("circleci"))' --json
kosmo integrations:lua --eval 'print(docs.read("circleci.api_delete"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local circleci = app.integrations.circleci
local result = circleci.api_delete({})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.circleci, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.circleci.default.* or app.integrations.circleci.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need CircleCI, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

CircleCI Lua Reference

Namespace: app.integrations.circleci

CircleCI tools use a personal API token sent as the Circle-Token header. Project slugs should be passed as a single string such as gh/example-org/example-repo.

Common Workflows

Trigger a pipeline:

local pipeline = app.integrations.circleci.trigger_pipeline({
  project_slug = "gh/example-org/example-repo",
  branch = "main",
  parameters = {
    deploy = false
  }
})

Inspect the pipeline and workflow:

local workflows = app.integrations.circleci.list_pipeline_workflows({
  pipeline_id = pipeline.id
})

local jobs = app.integrations.circleci.list_workflow_jobs({
  workflow_id = workflows.items[1].id
})

Manage a context secret:

app.integrations.circleci.upsert_context_env_var({
  context_id = "context-uuid",
  env_var_name = "DEPLOY_TOKEN",
  value = "secret-value"
})

Coverage Notes

project_slug and org_slug preserve slash-separated CircleCI slugs in API paths and query strings.
list_pipelines, list_projects, and context listing normalize org_slug, owner_slug, and page_token to CircleCI’s documented hyphenated query keys.
Pipeline tools cover trigger, continue, config, values, project pipelines, and pipeline workflows.
Workflow and job tools cover approvals, cancellation, reruns, workflow jobs, artifacts, and test metadata.
Project tools cover checkout keys, environment variables, settings, and project deletion.
Context tools cover context-level secrets and restrictions; secret values are write-only in CircleCI responses.
Raw api_get, api_post, api_patch, api_put, and api_delete can call any CircleCI API v2 endpoint path.

Responses are decoded CircleCI JSON exactly as returned by the API.

Raw agent markdown

# CircleCI Lua Reference

Namespace: `app.integrations.circleci`

CircleCI tools use a personal API token sent as the `Circle-Token` header. Project slugs should be passed as a single string such as `gh/example-org/example-repo`.

## Common Workflows

Trigger a pipeline:

```lua
local pipeline = app.integrations.circleci.trigger_pipeline({
  project_slug = "gh/example-org/example-repo",
  branch = "main",
  parameters = {
    deploy = false
  }
})
```

Inspect the pipeline and workflow:

```lua
local workflows = app.integrations.circleci.list_pipeline_workflows({
  pipeline_id = pipeline.id
})

local jobs = app.integrations.circleci.list_workflow_jobs({
  workflow_id = workflows.items[1].id
})
```

Manage a context secret:

```lua
app.integrations.circleci.upsert_context_env_var({
  context_id = "context-uuid",
  env_var_name = "DEPLOY_TOKEN",
  value = "secret-value"
})
```

## Coverage Notes

- `project_slug` and `org_slug` preserve slash-separated CircleCI slugs in API paths and query strings.
- `list_pipelines`, `list_projects`, and context listing normalize `org_slug`, `owner_slug`, and `page_token` to CircleCI's documented hyphenated query keys.
- Pipeline tools cover trigger, continue, config, values, project pipelines, and pipeline workflows.
- Workflow and job tools cover approvals, cancellation, reruns, workflow jobs, artifacts, and test metadata.
- Project tools cover checkout keys, environment variables, settings, and project deletion.
- Context tools cover context-level secrets and restrictions; secret values are write-only in CircleCI responses.
- Raw `api_get`, `api_post`, `api_patch`, `api_put`, and `api_delete` can call any CircleCI API v2 endpoint path.

Responses are decoded CircleCI JSON exactly as returned by the API.

Metadata-derived Lua example

local result = app.integrations.circleci.api_delete({})
print(result)

Functions

api_delete Write

Call any CircleCI API DELETE endpoint path.

Lua path: app.integrations.circleci.api_delete
Full name: circleci.circleci_api_delete

Parameter	Type	Required	Description
No parameters.

api_get Read

Call any CircleCI API GET endpoint path.

Lua path: app.integrations.circleci.api_get
Full name: circleci.circleci_api_get

Parameter	Type	Required	Description
No parameters.

api_patch Write

Call any CircleCI API PATCH endpoint path.

Lua path: app.integrations.circleci.api_patch
Full name: circleci.circleci_api_patch

Parameter	Type	Required	Description
No parameters.

api_post Write

Call any CircleCI API POST endpoint path.

Lua path: app.integrations.circleci.api_post
Full name: circleci.circleci_api_post

Parameter	Type	Required	Description
No parameters.

api_put Write

Call any CircleCI API PUT endpoint path.

Lua path: app.integrations.circleci.api_put
Full name: circleci.circleci_api_put

Parameter	Type	Required	Description
No parameters.

approve_workflow_job Write

Approve a workflow approval job.

Lua path: app.integrations.circleci.approve_workflow_job
Full name: circleci.circleci_approve_workflow_job

Parameter	Type	Required	Description
No parameters.

cancel_job_by_id Write

Cancel a job by job ID.

Lua path: app.integrations.circleci.cancel_job_by_id
Full name: circleci.circleci_cancel_job_by_id

Parameter	Type	Required	Description
No parameters.

cancel_job_by_number Write

Cancel a job by project slug and job number.

Lua path: app.integrations.circleci.cancel_job_by_number
Full name: circleci.circleci_cancel_job_by_number

Parameter	Type	Required	Description
No parameters.

cancel_workflow Write

Cancel a workflow.

Lua path: app.integrations.circleci.cancel_workflow
Full name: circleci.circleci_cancel_workflow

Parameter	Type	Required	Description
No parameters.

continue_pipeline Write

Continue a setup workflow pipeline with generated configuration.

Lua path: app.integrations.circleci.continue_pipeline
Full name: circleci.circleci_continue_pipeline

Parameter	Type	Required	Description
No parameters.

create_checkout_key Write

Create a checkout key for a project.

Lua path: app.integrations.circleci.create_checkout_key
Full name: circleci.circleci_create_checkout_key

Parameter	Type	Required	Description
No parameters.

create_context Write

Create a CircleCI context.

Lua path: app.integrations.circleci.create_context
Full name: circleci.circleci_create_context

Parameter	Type	Required	Description
No parameters.

create_context_restriction Write

Create a context restriction.

Lua path: app.integrations.circleci.create_context_restriction
Full name: circleci.circleci_create_context_restriction

Parameter	Type	Required	Description
No parameters.

create_project_env_var Write

Create a project environment variable.

Lua path: app.integrations.circleci.create_project_env_var
Full name: circleci.circleci_create_project_env_var

Parameter	Type	Required	Description
No parameters.

create_schedule Write

Create a schedule trigger for a project.

Lua path: app.integrations.circleci.create_schedule
Full name: circleci.circleci_create_schedule

Parameter	Type	Required	Description
No parameters.

create_webhook Write

Create an outbound webhook.

Lua path: app.integrations.circleci.create_webhook
Full name: circleci.circleci_create_webhook

Parameter	Type	Required	Description
No parameters.

delete_checkout_key Write

Delete a project checkout key.

Lua path: app.integrations.circleci.delete_checkout_key
Full name: circleci.circleci_delete_checkout_key

Parameter	Type	Required	Description
No parameters.

delete_context Write

Delete a context and its environment variables.

Lua path: app.integrations.circleci.delete_context
Full name: circleci.circleci_delete_context

Parameter	Type	Required	Description
No parameters.

delete_context_env_var Write

Delete a context environment variable.

Lua path: app.integrations.circleci.delete_context_env_var
Full name: circleci.circleci_delete_context_env_var

Parameter	Type	Required	Description
No parameters.

delete_context_restriction Write

Delete a context restriction.

Lua path: app.integrations.circleci.delete_context_restriction
Full name: circleci.circleci_delete_context_restriction

Parameter	Type	Required	Description
No parameters.

delete_project Write

Delete a project by project slug.

Lua path: app.integrations.circleci.delete_project
Full name: circleci.circleci_delete_project

Parameter	Type	Required	Description
No parameters.

delete_project_env_var Write

Delete a project environment variable.

Lua path: app.integrations.circleci.delete_project_env_var
Full name: circleci.circleci_delete_project_env_var

Parameter	Type	Required	Description
No parameters.

delete_schedule Write

Delete a schedule by ID.

Lua path: app.integrations.circleci.delete_schedule
Full name: circleci.circleci_delete_schedule

Parameter	Type	Required	Description
No parameters.

delete_webhook Write

Delete an outbound webhook.

Lua path: app.integrations.circleci.delete_webhook
Full name: circleci.circleci_delete_webhook

Parameter	Type	Required	Description
No parameters.

get_checkout_key Read

Get a project checkout key by fingerprint.

Lua path: app.integrations.circleci.get_checkout_key
Full name: circleci.circleci_get_checkout_key

Parameter	Type	Required	Description
No parameters.

get_context Read

Get a context by ID.

Lua path: app.integrations.circleci.get_context
Full name: circleci.circleci_get_context

Parameter	Type	Required	Description
No parameters.

get_current_user Read

Get the authenticated CircleCI user profile.

Lua path: app.integrations.circleci.get_current_user
Full name: circleci.circleci_get_current_user

Parameter	Type	Required	Description
No parameters.

get_job_details Read

Get job details by project slug and job number.

Lua path: app.integrations.circleci.get_job_details
Full name: circleci.circleci_get_job_details

Parameter	Type	Required	Description
No parameters.

get_pipeline Read

Get details for a pipeline by ID.

Lua path: app.integrations.circleci.get_pipeline
Full name: circleci.circleci_get_pipeline

Parameter	Type	Required	Description
No parameters.

get_pipeline_config Read

Get compiled configuration for a pipeline.

Lua path: app.integrations.circleci.get_pipeline_config
Full name: circleci.circleci_get_pipeline_config

Parameter	Type	Required	Description
No parameters.

get_pipeline_values Read

Get pipeline parameter values for a pipeline.

Lua path: app.integrations.circleci.get_pipeline_values
Full name: circleci.circleci_get_pipeline_values

Parameter	Type	Required	Description
No parameters.

get_project Read

Get a project by project slug.

Lua path: app.integrations.circleci.get_project
Full name: circleci.circleci_get_project

Parameter	Type	Required	Description
No parameters.

get_project_env_var Read

Get a masked project environment variable.

Lua path: app.integrations.circleci.get_project_env_var
Full name: circleci.circleci_get_project_env_var

Parameter	Type	Required	Description
No parameters.

get_project_insights_summary Read

Get project summary metrics and trends.

Lua path: app.integrations.circleci.get_project_insights_summary
Full name: circleci.circleci_get_project_insights_summary

Parameter	Type	Required	Description
No parameters.

get_project_pipeline_by_number Read

Get a project pipeline by pipeline number.

Lua path: app.integrations.circleci.get_project_pipeline_by_number
Full name: circleci.circleci_get_project_pipeline_by_number

Parameter	Type	Required	Description
No parameters.

get_project_settings Read

Get project settings.

Lua path: app.integrations.circleci.get_project_settings
Full name: circleci.circleci_get_project_settings

Parameter	Type	Required	Description
No parameters.

get_schedule Read

Get a schedule by ID.

Lua path: app.integrations.circleci.get_schedule
Full name: circleci.circleci_get_schedule

Parameter	Type	Required	Description
No parameters.

get_user Read

Get a CircleCI user by ID.

Lua path: app.integrations.circleci.get_user
Full name: circleci.circleci_get_user

Parameter	Type	Required	Description
No parameters.

get_webhook Read

Get an outbound webhook.

Lua path: app.integrations.circleci.get_webhook
Full name: circleci.circleci_get_webhook

Parameter	Type	Required	Description
No parameters.

get_workflow Read

Get details for a workflow.

Lua path: app.integrations.circleci.get_workflow
Full name: circleci.circleci_get_workflow

Parameter	Type	Required	Description
No parameters.

get_workflow_job_timeseries Read

Get timeseries data for a workflow job.

Lua path: app.integrations.circleci.get_workflow_job_timeseries
Full name: circleci.circleci_get_workflow_job_timeseries

Parameter	Type	Required	Description
No parameters.

get_workflow_metrics Read

Get metrics and recent runs for a workflow.

Lua path: app.integrations.circleci.get_workflow_metrics
Full name: circleci.circleci_get_workflow_metrics

Parameter	Type	Required	Description
No parameters.

list_checkout_keys Read

List checkout keys for a project.

Lua path: app.integrations.circleci.list_checkout_keys
Full name: circleci.circleci_list_checkout_keys

Parameter	Type	Required	Description
No parameters.

list_collaborations Read

List VCS collaborations for the authenticated user.

Lua path: app.integrations.circleci.list_collaborations
Full name: circleci.circleci_list_collaborations

Parameter	Type	Required	Description
No parameters.

list_context_env_vars Read

List environment variables in a context without values.

Lua path: app.integrations.circleci.list_context_env_vars
Full name: circleci.circleci_list_context_env_vars

Parameter	Type	Required	Description
No parameters.

list_context_restrictions Read

List context restrictions.

Lua path: app.integrations.circleci.list_context_restrictions
Full name: circleci.circleci_list_context_restrictions

Parameter	Type	Required	Description
No parameters.

list_contexts Read

List contexts for an owner.

Lua path: app.integrations.circleci.list_contexts
Full name: circleci.circleci_list_contexts

Parameter	Type	Required	Description
No parameters.

list_flaky_tests Read

List flaky tests for a project.

Lua path: app.integrations.circleci.list_flaky_tests
Full name: circleci.circleci_list_flaky_tests

Parameter	Type	Required	Description
No parameters.

list_insight_branches Read

List branches with insight data for a project.

Lua path: app.integrations.circleci.list_insight_branches
Full name: circleci.circleci_list_insight_branches

Parameter	Type	Required	Description
No parameters.

list_job_artifacts Read

List artifacts for a job.

Lua path: app.integrations.circleci.list_job_artifacts
Full name: circleci.circleci_list_job_artifacts

Parameter	Type	Required	Description
No parameters.

list_job_tests Read

List test metadata for a job.

Lua path: app.integrations.circleci.list_job_tests
Full name: circleci.circleci_list_job_tests

Parameter	Type	Required	Description
No parameters.

list_pipeline_workflows Read

List workflows for a pipeline.

Lua path: app.integrations.circleci.list_pipeline_workflows
Full name: circleci.circleci_list_pipeline_workflows

Parameter	Type	Required	Description
No parameters.

list_pipelines Read

List pipelines visible to the authenticated user or organization.

Lua path: app.integrations.circleci.list_pipelines
Full name: circleci.circleci_list_pipelines

Parameter	Type	Required	Description
No parameters.

list_project_env_vars Read

List masked project environment variables.

Lua path: app.integrations.circleci.list_project_env_vars
Full name: circleci.circleci_list_project_env_vars

Parameter	Type	Required	Description
No parameters.

list_project_pipelines Read

List pipelines for a project.

Lua path: app.integrations.circleci.list_project_pipelines
Full name: circleci.circleci_list_project_pipelines

Parameter	Type	Required	Description
No parameters.

list_projects Read

List projects for an organization.

Lua path: app.integrations.circleci.list_projects
Full name: circleci.circleci_list_projects

Parameter	Type	Required	Description
No parameters.

list_schedule_triggers Read

List schedule triggers for a project.

Lua path: app.integrations.circleci.list_schedule_triggers
Full name: circleci.circleci_list_schedule_triggers

Parameter	Type	Required	Description
No parameters.

list_webhooks Read

List outbound webhooks.

Lua path: app.integrations.circleci.list_webhooks
Full name: circleci.circleci_list_webhooks

Parameter	Type	Required	Description
No parameters.

list_workflow_job_metrics Read

List job metrics for a project workflow.

Lua path: app.integrations.circleci.list_workflow_job_metrics
Full name: circleci.circleci_list_workflow_job_metrics

Parameter	Type	Required	Description
No parameters.

list_workflow_jobs Read

List jobs for a workflow.

Lua path: app.integrations.circleci.list_workflow_jobs
Full name: circleci.circleci_list_workflow_jobs

Parameter	Type	Required	Description
No parameters.

list_workflow_metrics Read

List workflow metrics for a project.

Lua path: app.integrations.circleci.list_workflow_metrics
Full name: circleci.circleci_list_workflow_metrics

Parameter	Type	Required	Description
No parameters.

list_workflows Read

List all workflows for a specific CircleCI pipeline. Shows workflow names, statuses (running, success, failed, etc.), and timing information.

Lua path: app.integrations.circleci.list_workflows
Full name: circleci.circleci_list_workflows

Parameter	Type	Required	Description
`pipeline_id`	string	yes	The pipeline ID (UUID) to list workflows for.

rerun_workflow Write

Rerun a workflow.

Lua path: app.integrations.circleci.rerun_workflow
Full name: circleci.circleci_rerun_workflow

Parameter	Type	Required	Description
No parameters.

trigger_pipeline Write

Trigger a new pipeline for a project.

Lua path: app.integrations.circleci.trigger_pipeline
Full name: circleci.circleci_trigger_pipeline

Parameter	Type	Required	Description
No parameters.

update_project_settings Write

Update project settings.

Lua path: app.integrations.circleci.update_project_settings
Full name: circleci.circleci_update_project_settings

Parameter	Type	Required	Description
No parameters.

update_schedule Write

Update a schedule by ID.

Lua path: app.integrations.circleci.update_schedule
Full name: circleci.circleci_update_schedule

Parameter	Type	Required	Description
No parameters.

update_webhook Write

Update an outbound webhook.

Lua path: app.integrations.circleci.update_webhook
Full name: circleci.circleci_update_webhook

Parameter	Type	Required	Description
No parameters.

upsert_context_env_var Write

Add or update a context environment variable.

Lua path: app.integrations.circleci.upsert_context_env_var
Full name: circleci.circleci_upsert_context_env_var

Parameter	Type	Required	Description
No parameters.