Skip to main content

​
CLI Overview

Use the Cloudgeni CLI to operate Cloudgeni from a terminal, a script, or a coding agent. It is useful for:
  • Chatting with an active AI DevOps session
  • Starting agent work from scripts or another coding agent
  • Inspecting integrations, resources, scans, findings, and policies
  • Reusing a selected organization across commands
  • Getting JSON output for automation

​
Installation

With Homebrew (macOS and Linux):
Or with the install script:
Homebrew handles upgrades with brew upgrade cloudgeni. The install script verifies the published checksum, places the binary in ~/.cloudgeni/bin, and configures PATH for Zsh, Bash, or Fish. Run the exact source "..." command it prints to activate cloudgeni in the current terminal, or open a new terminal. Verify without relying on PATH:

​
Create An API Key

The CLI needs an organization-scoped API key to talk to the API. Create one in the web app under Settings -> Developers -> API Keys, then copy the cgk_... value — it is shown once at creation time. Authenticate interactively and paste the key when prompted:
The CLI detects the cgk_... format, uses the required API-key header, verifies organization access, and then stores the credential locally. For a non-interactive local login, use cloudgeni auth login --key "$CLOUDGENI_API_KEY". Do not pass a cgk_... key through --token. For CI and scripts, set CLOUDGENI_API_KEY in the environment instead of storing credentials with auth login.

​
Setup

cloudgeni org use selects the default organization for future commands. You can still pass --org <org> on any command when you need a one-off override. cloudgeni org current --json is the authoritative check for the organization used when --org is omitted. cloudgeni auth status --json reports both that active organization and the organization stored with the credential; they can differ after org use. cloudgeni context use selects default repository and integration context for agent sessions in that organization. You can still pass context flags on one command when you need a one-off override.

​
Agent Context

Select the repo and integrations once, then let cloudgeni agent and cloudgeni agent run reuse them for new sessions:
For repository-only changes:
Repository values can be repository IDs, owner/name, URLs, or unambiguous names. Integration values can be IDs, names, or provider aliases.

​
Agent Sessions

Open the active session for the selected organization:
Send one message, stream the response, and return:
Check or change the active session:
Inside the interactive shell, use:
  • /help for available shell commands
  • /session to show the active session
  • /session <id> to attach to another session
  • /new to start a new session on the next message
  • /watch to stream the current session
  • /org to show the selected organization
  • /exit to leave the shell

​
Agent Automation

Use explicit subcommands when another tool or script is driving Cloudgeni:
For machine-readable output:
Use --fields to keep large JSON responses focused. Paths are relative to the response data property and traverse arrays automatically:

​
Agent Skills

Cloudgeni publishes a cloudgeni-cli skill for Claude Code and Codex. It translates requests such as “show my highest-severity open drift findings” or “continue this Cloudgeni agent session” into safe, non-interactive CLI calls. For Claude Code, install the public plugin:
For Codex, ask the built-in skill installer to install the skill directory from the public repository:
Codex can then select the skill automatically for Cloudgeni requests, or you can invoke it with $cloudgeni-cli. The skill requires the cloudgeni CLI to be installed and authenticated; it does not include credentials or bypass a coding agent’s network sandbox.

​
Finding Context

Use these commands when you want to inspect available context directly:

​
Integrations

List connected integrations:
Create GitHub integration setup links:
Create an Azure cloud integration:

​
Global Flags

  • --json or --output json for machine-readable output
  • --fields <path,...> to project JSON data to selected dot paths
  • --non-interactive to disable prompts
  • --org <org> to override the selected organization for one command
  • --token to override an explicit bearer token for one command (never use it for cgk_... keys)