What this gives you

With the armoctl extension installed, Gemini can translate natural-language security questions into armoctl commands and return clear, summarized answers. Ask Gemini "which runtime incidents are Critical in my staging cluster?" and it runs armoctl incidents list --severity Critical --cluster staging, reads the JSON output, and presents the key findings. Read operations execute immediately. Mutations — creating exceptions, generating policies, creating Jira tickets — produce a dry-run preview first so you can review the exact change before it is committed.

Install

Gemini CLI uses a different extension format from Claude Code. The armoctl repository ships a gemini-extension.json manifest at the root, which Gemini CLI reads to discover the available skills.

Install the extension:

gemini extension install https://github.com/armosec/armoctl

Gemini CLI first tries to fetch a release-asset bundle from GitHub Releases. armoctl does not currently publish that bundle, so you will see:

Error downloading github release for https://github.com/armosec/armoctl ... 404
Would you like to attempt to install via "git clone" instead?
Do you want to continue? [Y/n]:

Answer Y — Gemini CLI clones the repo and reads gemini-extension.json directly. After accepting the (one-time) review prompts about hooks and agent skills, you should see:

Extension "armoctl" installed successfully and enabled.

Verify with gemini extension list.

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 (preferred for headless agents 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 the extension provides

The extension loads the same skill set as the Claude Code 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 auto-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.

Gemini CLI extensions support a SessionStart hook, and armoctl ships one. On the first session after installing the extension, the hook checks whether the armoctl binary is on PATH and runs the official installer if it is missing. On subsequent sessions, it keeps the binary on the same version as the extension (running armoctl update whenever they drift). If you ever need to update outside a session, run armoctl update directly.

Example prompts

"What are the most critical security risks in cluster prod-us?"
"Show me Critical CVEs that are actually running in memory, not just present in an image layer."
"Add a 30-day exception for risk R-5678 — remediation is scheduled for next sprint."
"Generate a NetworkPolicy for the checkout service in the orders namespace."
"Which posture frameworks have the most failing controls in cluster dev?"
"Create a Jira ticket for the top Critical incident from today."

Troubleshooting

armoctl: command not found — the SessionStart hook should auto-install the binary on first session. If it kept failing, install manually: curl -fsSL https://package-distribution.armosec.io/armoctl/install.sh | bash
Authentication errors — run armoctl configure or check that ARMO_CUSTOMER_GUID and ARMO_ACCESS_KEY are set in the environment where Gemini CLI runs.
401 / 403 responses — credentials have expired or belong to a different tenant. Regenerate an access key at the URL above and re-run armoctl configure.