GitHub Copilot CLI plugin

Install the armoctl plugin in GitHub Copilot CLI to drive ARMO from natural-language prompts.

What the plugin gives you

Once the plugin is installed, Copilot can translate natural-language security questions into precise armoctl commands and summarize the results for you. Ask Copilot "what's the most critical risk in cluster prod-eu?" and it loads the risks skill, runs armoctl risks list --severity Critical, narrows the affected resources to that cluster, and gives you a human-readable summary. Read operations work immediately; mutations such as creating exceptions, generating network policies, or opening Jira tickets show you a dry-run preview first and run only after you confirm in the conversation.

The plugin is the same one that ships for Claude Code and Gemini CLI — same skills, same SessionStart hook — installed through Copilot CLI's plugin marketplace support.

Supported surfaces

GitHub Copilot CLI (the copilot terminal command), interactive and prompt mode (copilot -p). Copilot cloud agent and VS Code agent plugins are not covered by this page.

Install

copilot plugin marketplace add armosec/armoctl
copilot plugin install armoctl@armosec

Check that it loaded:

copilot plugin list

Inside a session, /skills list shows the armoctl skill and the 13 armoctl-* cluster skills.

The first time a session starts after install, the SessionStart hook checks whether the armoctl binary is present on PATH and, if not, installs the version that matches the plugin into ~/.local/bin. After that, whenever the binary's version differs from the plugin's, the hook reinstalls the plugin's version in place, so the binary always matches the skills it ships with. Copilot shows the hook's message in the session when it installs the binary or when something needs your attention.

Configure once

You need two credentials:

Customer GUID — ARMO Platform UI → top-right account dropdown.
Access Key — generate one at cloud.armosec.io/settings/workspace/agent-access-keys (EU) or cloud.us.armosec.io/settings/workspace/agent-access-keys (US).

Then either run the interactive setup:

armoctl configure

Or set environment variables before starting copilot (preferred for headless use and CI):

export ARMO_CUSTOMER_GUID=...
export ARMO_ACCESS_KEY=...
export ARMO_API_BASE_URL=api.armosec.io   # api.us.armosec.io for US tenants

Credentials are stored at ~/.armoctl/config.yaml.

What's in the plugin

Root armoctl skill — covers setup, the JSON output contract (--full / --fields / --query), the mutation safety contract (--dry-run / --yes), and error semantics.
13 per-cluster skills loaded by description match when your request touches that cluster: armoctl-incidents, armoctl-vulns, armoctl-posture, armoctl-risks, armoctl-attack-chains, armoctl-inventory, armoctl-network-policies, armoctl-seccomp, armoctl-runtime-rules, armoctl-runtime-policies, armoctl-integrations, armoctl-cloud-accounts, armoctl-repo-posture. Each one carries the mutation rule, so it applies even when only the cluster skill is loaded.
SessionStart hook — verifies the binary is present and version-matched at the start of every session, so the plugin stays self-sufficient after the first install.

How mutations work

For any command that changes something in ARMO, Copilot:

runs it with --dry-run and shows you what will change;
asks you to confirm in the conversation;
after you answer yes, runs the same command with --yes.

Copilot CLI also asks for your approval before it runs each shell command. Choosing Yes, and don't ask again for armoctl is convenient for read-heavy sessions; keep the per-command prompt if you want a second gate in front of every write.

Example prompts

"What's the most critical security risk in cluster prod-eu?"
"Which Critical CVEs are loaded at runtime, not just sitting on disk?"
"Create a 30-day exception for risk R_0037 on the frontend workload — we have compensating controls."
"Generate a NetworkPolicy for the frontend workload in the payments namespace."
"Which posture controls are failing, grouped by framework?"
"Open a Jira ticket for the most recent Critical runtime incident."

Troubleshooting

armoctl: command not found — the SessionStart hook installs the binary into ~/.local/bin. Make sure that directory is on your PATH, then start a new session. To install manually: curl -fsSL https://package-distribution.armosec.io/armoctl/install.sh | bash -s -- --dir "$HOME/.local/bin"
Classic Personal Access Tokens (ghp_) are not supported by Copilot — Copilot CLI is picking up a classic token from GITHUB_TOKEN or GH_TOKEN. Unset it and sign in with copilot → /login, or use a fine-grained token.
Plugin installed but no armoctl skills — run copilot plugin list and check that armoctl@armosec is enabled. A project or personal skill with the same name takes precedence over the plugin's.
Updating the plugin — copilot plugin marketplace update armosec, then copilot plugin update armoctl. The hook updates the binary on the next session.
Authentication errors, 401 / 403 responses — run armoctl configure or verify your environment variables. If the access key expired or belongs to a different tenant, regenerate it at the URL above.