Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Why use it

AI assistants are eager but uninformed about Control Plane. Out of the box, they will:
  • Pick the wrong workload type (e.g. standard when you needed stateful for persistent storage)
  • Skip steps in the 3-step secret access chain — the workload deploys, then silently fails at runtime
  • Prefix images with docker.io/ (which Control Plane does not accept)
  • Forget the firewall defaults (everything blocked) and ship a workload that can’t reach its database
  • Burn tokens polling deployment status in a loop instead of using cpln apply --ready
  • Silently downgrade conflicting configuration to a “safe” default that ships an under-provisioning bug
The AI plugin fixes this. It teaches your assistant the platform, runs the multi-step workflows for you, and enforces guardrails that prevent the most common production failures.

​
What it does

The plugin gives your AI three things:
ComponentWhat it doesWhen it activates
23 SkillsPlatform knowledge — workload types, CLI, autoscaling, secrets, networking, observability, IaC, mk8s, BYOK, templatesLoaded on demand when relevant to your prompt
8 Agents + 8 CommandsMulti-step workflows — troubleshoot a failing workload, set up the full secret access chain, configure a domain, migrate from Kubernetes, set up cloud identityTriggered by your prompt or by /cpln:<command>
8 Guardrail RulesAlways-on enforcement — confirm destructive ops, surface constraint conflicts, never poll from the AI layer, validate manifest fieldsLoaded into every session
It also pre-configures the Control Plane MCP Server (80+ tools) so the assistant can actually act on your infrastructure — create workloads, manage secrets, query state — not just talk about it.

​
Install

/plugins add controlplane-com/ai-plugin

​
Authenticate the MCP server

The MCP server needs a service account token to act on your behalf. Skills, agents, commands, and guardrails work without it — the token is only required for live operations (creating workloads, managing secrets, applying manifests). 
export CPLN_TOKEN="<your-service-account-token>"
Create a service account with the Create a Service Account guide. Add it to the superusers group for full access, or viewers for read-only exploration. Gemini CLI prompts for the token during install and stores it in your system keychain.

​
Your first useful prompt

Try one of these to see the plugin in action: 
/cpln:troubleshoot my-api --gvc production
For the secret-setup prompt, the plugin will create the identity, link it to the workload, create the policy with reveal permission, and inject the secret as an env var — all three required steps, in the right order.

​
How to prompt it well

The plugin removes most of the burden of being precise — it knows the platform — but a few habits compound the value:

​
Set context once, at the start

Before destructive or stateful work, name the org, profile, and GVC explicitly. The plugin will refuse to mutate state silently against whatever your active CLI profile happens to point at. 
Use org "acme-prod" and GVC "us-east" for the rest of this session.

​
Describe the goal, not the technique

Let the plugin pick the workload type, autoscaling strategy, and firewall rules from the constraints. If you say serverless when you need stateful, the plugin will surface the conflict — but you’ve spent a turn fixing it.
Good
I need a Redis-backed cache that survives pod restarts, public on
my domain, traffic ~100 rps with bursts to 500.
Less good
Create a stateful workload with 1 replica, port 6379, ext4 volume,
and disabled autoscaling.

​
Let the CLI wait, not the AI

For deploys, the plugin uses cpln apply --ready (CLI-native blocking) or a fail-fast shell wait for first-deploys. Don’t ask it to “keep checking until it’s ready” — that burns tokens for no diagnostic value.

​
Confirm destructive operations explicitly

The plugin will present a structured summary (action, blast radius, reversibility, mitigation) before any delete, redeploy, or implicit recreate caused by changing an immutable field. Reply with a clear yes — silence and “maybe later” are treated as no.

​
What the guardrails enforce

These are loaded into every session and prevent the most common production failures. Each one exists because a real incident happened:
GuardrailWhat it does
Org / Profile / GVC confirmationRefuses to mutate state until target org, profile, and GVC are unambiguously established. Read-only commands announce the target before running.
3-step secret access chainRefuses to consider a workload “configured for secrets” without identity + policy + secret reference.
Image rulesNo docker.io/ prefix; own-org registry uses //image/NAME:TAG; cross-org uses hostname form; all images linux/amd64; port matches container.
Workload type constraintsCatches incompatible combinations (Capacity AI + stateful, scale-to-zero + cron, immutable type changes that require delete + recreate).
Destructive operation confirmationPresents action, blast radius, reversibility, and mitigation. Treats immutable-field changes (rename, type change, filesystem change) as destructive.
Constraint conflict surfacingWhen your request hits a compatibility limit, lists realistic alternatives with a project-grounded recommendation. Never silently downgrades to disabled / none / 1 replica.
Long-running operationsUses CLI-native blocking and shell waits. Never burns tokens polling status from the AI layer.
CLI command accuracyNever writes a cpln command from memory. Verifies command structure against the resource map first.

​
Best practices

  • Use service account tokens, not user tokens — especially in CI/CD. Create with cpln serviceaccount add-key.
  • Scope the service account to the smallest permission set that fits the use case. superusers for development environments, custom policies for production.
  • Set context per-session, not per-prompt — once at the start, then let the plugin reuse it.
  • Read the diff before applying — when the plugin offers a manifest, scan it. The plugin makes mistakes infrequent, not zero.
  • Keep prompts goal-oriented — "deploy a Postgres-backed API" is a better starting point than "create a workload with these 14 fields". The plugin’s job is to translate intent into platform-correct configuration.
  • For repeated workflows, prefer the slash commands over freeform prompts — /cpln:troubleshoot, /cpln:setup-secret, /cpln:migrate-k8s. They’re shorter and more predictable than re-explaining the workflow each time.

​
When you can’t install the full plugin

If your tool doesn’t support plugins (Cursor, Amp, OpenCode, or others), install the core skill alone: 
npx skills add https://docs.controlplane.com
Or point any tool directly to the skill file: 
https://docs.controlplane.com/skill.md
The skill-only path gives you platform knowledge (workload types, CLI commands, autoscaling, networking, gotchas, verification checklist). It does not include agents, commands, guardrail rules, or MCP pre-configuration. To add MCP separately, follow the setup guide for your tool.

​
Full inventory

The tables above summarize the plugin. For the complete list of every skill, agent, command, and guardrail rule — with descriptions and trigger conditions — see the plugin README on GitHub.

​
Next steps

MCP Server

The 80+ tools the plugin uses to act on your infrastructure

Usage Examples

Concrete prompts for common Control Plane workflows

Create a Service Account

Generate the token the MCP server needs to authenticate

Plugin source

Source, full inventory, and contribution guide