cloudgeni-cli

# Cloudgeni CLI `cloudgeni` is the command-line interface for the Cloudgeni platform (cloud governance: resource inventory, IaC/drift/compliance scanning, policies, and background AI DevOps agents). ## Setup check ```bash cloudgeni --version || curl -fsSL https://github.com/Cloudgeni-ai/cloudgeni-cli/releases/latest/download/install.sh | bash cloudgeni auth status --json ``` If not authenticated, ask the user to create an organization API key in Cloudgeni and run `cloudgeni auth login`, or use the key non-interactively: ```bash cloudgeni auth login --key "$CLOUDGENI_API_KEY" # persists to ~/.cloudgeni/auth.json # or per-invocation, no persistence: CLOUDGENI_API_KEY=... cloudgeni org list --json ``` Bearer and OAuth tokens remain explicit compatibility paths. Pass them with `--method token --token ...` or `--method oauth --token ...`; never pass a `cgk_...` API key through `--token`. Credential precedence: `--token` flag > `CLOUDGENI_TOKEN` env (Bearer) > `CLOUDGENI_API_KEY` env (`cgk_...` API key) > `~/.cloudgeni/auth.json`. ## Rules for agent (scripted) use 1. **Always pass `--json`.** It forces machine-readable output AND non-interactive mode, and suppresses update banners. Without it, missing flags trigger interactive prompts that will hang a non-TTY session. Exception: `agent watch`, `agent run --watch`, and `agent send --watch` reject `--json` with a `VALIDATION_ERROR` — run them with `--non-interactive` instead, or drop `--watch` to get a JSON response. (`system stream connect` streams raw SSE; pass `--follow=false` for a JSON response.) 2. **Pass every required flag explicitly.** In JSON mode any missing required flag is an immediate `VALIDATION_ERROR` instead of a prompt. 3. **Scope explicitly**: most commands take `--org <id|slug>`; workspace-scoped ones also take `--workspace <id|slug>`. Resolve once via `cloudgeni org list --json`, or set a default: `cloudgeni org use <org>` (persists `defaultOrgId`). 4. **Destructive commands require `--yes`** (`-y`): all `delete` subcommands, `org users remove`, `pipeline runs cancel`, `agent sessions cancel`. Never pass `--yes` unless the user asked for the deletion. 5. **Request bodies**: mutation commands accept `--body '<json object>'` (must be an object). Specific flags (e.g. `--name`) merge OVER `--body`. 6. **Query flags**: array flags accept repetition or comma-separated values (`--status A --status B` → `?status=A,B`). 7. **Errors**: non-zero exit with JSON error payload. Codes: `VALIDATION_ERROR`, `AUTH_ERROR`, `API_ERROR`, `TIMEOUT`, `CANCELLED`. Use `--request-timeout <seconds>` for slow endpoints. Reliable invocation shape: ```bash cloudgeni <group> <subcommand> --json --org <org> [--workspace <ws>] [flags...] [--yes] ``` ## Orientation | Task | Command | | --- | --- | | Who am I / auth state | `cloudgeni auth status --json` | | List orgs | `cloudgeni org list --json` | | Set default org | `cloudgeni org use <org>` | | CLI vs API version | `cloudgeni system version --json` | | List integrations | `cloudgeni integration list --json --org <org>` | | List repos | `cloudgeni repo list --json --org <org>` | | Cloud resource inventory | `cloudgeni cloud resources list --json --org <org> --integration <int_id>` | | Drift scans | `cloudgeni drift scans list --json --org <org>` | | Drift findings | `cloudgeni drift findings list --json --org <org> --severity HIGH` | | Start a drift scan | `cloudgeni drift scans create --json --org <org>` | | Policies | `cloudgeni policy list --json --org <org>` | | Audit log export | `cloudgeni audit-log export --org <org> --format ndjson > audit.ndjson` | Three different "defaults" — don't confuse them: - `cloudgeni org use` — default organization (`defaultOrgId`). - `cloudgeni repo use [repo]` — default repository/branch for agent sessions. - `cloudgeni context use [repo]` — full default agent context (repos, branches, git/cloud/doc integrations) per org. ## Background AI DevOps agents ```bash # Start a session with a prompt; --json (without --watch) returns the session id cloudgeni agent run "audit our storage accounts for public access" --json --org <org> --repo owner/name@main # Or stream live output instead (--watch is incompatible with --json) cloudgeni agent run "audit our storage accounts for public access" --non-interactive --org <org> --repo owner/name@main --watch # Send a follow-up / watch an existing session cloudgeni agent send <session_id> "also check firewall rules" --watch cloudgeni agent watch <session_id> # Session management cloudgeni agent sessions list --json --org <org> cloudgeni agent sessions get --json --org <org> --session <session_id> cloudgeni agent current / switch <session_id> / clear ``` `agent run` accepts `--context-file target=local` to upload files into the session. It rejects legacy `--env KEY=VALUE`; use connected integrations or managed credentials instead. When a target session predates the current runtime and is read-only, current CLI releases automatically continue it into a new session and resend the message. If automatic continuation itself fails, follow the returned error hint or run `cloudgeni agent clear` and start a new session. ## Config `~/.cloudgeni/config.json` (override home with `CLOUDGENI_HOME`). Keys: `apiUrl`, `appUrl`, `autoupdate` (`true|false|notify`), `defaultOrgId`. ```bash cloudgeni config list --json cloudgeni config set --key apiUrl --value https://api.example.com # CLOUDGENI_API_URL env overrides at runtime ``` ## Full command reference Read [reference.md](reference.md) for the complete catalog of all command groups, subcommands, and flags (org, integration, repo, iac-scan, static-analysis, drift, cloud, pipeline, policy, event, audit-log, billing, user, admin, agent, support-case, vars, analytics, system, email, webhook, upgrade).