> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudgeni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> Use the Cloudgeni CLI to start, resume, and automate agent sessions from a terminal.

# CLI Overview

Use the Cloudgeni CLI when you want the same agent-session workflow from a terminal.

It is useful for:

* Chatting with an active AI DevOps session
* Starting agent work from scripts or another coding agent
* Reusing a selected organization across commands
* Getting JSON output for automation

## Installation

With Homebrew (macOS and Linux):

```bash theme={null}
brew install cloudgeni-ai/tap/cloudgeni
```

Or with the install script:

```bash theme={null}
curl -fsSL https://github.com/Cloudgeni-ai/cloudgeni-cli/releases/latest/download/install.sh | bash
```

Homebrew handles upgrades with `brew upgrade cloudgeni`; the install script places the
binary in `~/.cloudgeni/bin` and adds it to your shell profile.

Verify the install:

```bash theme={null}
cloudgeni --version
```

## 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 the CLI with it:

```bash theme={null}
cloudgeni auth login --method api-key --key cgk_...
```

For CI and scripts, set `CLOUDGENI_API_KEY` in the environment instead of storing credentials with
`auth login`.

## Setup

```bash theme={null}
cloudgeni auth login
cloudgeni org use
cloudgeni context use
cloudgeni org current
```

`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 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:

```bash theme={null}
cloudgeni context use acme/infra@main --cloud-integration aws
cloudgeni context current
```

For repository-only changes:

```bash theme={null}
cloudgeni repo use acme/infra@main
cloudgeni repo current
cloudgeni repo clear
```

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:

```bash theme={null}
cloudgeni agent
```

Send one message, stream the response, and return:

```bash theme={null}
cloudgeni agent "Investigate the latest infrastructure drift and suggest the safest next step"
```

Check or change the active session:

```bash theme={null}
cloudgeni agent current
cloudgeni agent switch <session>
cloudgeni agent clear
```

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:

```bash theme={null}
cloudgeni agent run "Create a plan to fix this drift" \
  --repo <repo[@branch]> \
  --cloud-integration <integration> \
  --watch

cloudgeni agent send <session> "Continue with the lowest-risk fix" --watch
cloudgeni agent watch <session>
```

For machine-readable output:

```bash theme={null}
cloudgeni agent current --json
cloudgeni agent run "Summarize the current repo risks" --json --non-interactive
```

## Finding Context

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

```bash theme={null}
cloudgeni org list --json
cloudgeni integration list --org <org>
cloudgeni repo list --org <org>
cloudgeni cloud resources list --org <org> --integration <integration>
```

## Integrations

List connected integrations:

```bash theme={null}
cloudgeni integration list
```

Create GitHub integration setup links:

```bash theme={null}
cloudgeni integration create github \
  --org <org> \
  --wait \
  --print-url
```

Create an Azure cloud integration:

```bash theme={null}
cloudgeni integration create azure \
  --org <org> \
  --subscription <subscription-id> \
  --tenant <tenant-id> \
  --name <integration-name> \
  --credential-client-id <client-id> \
  --credential-client-secret <client-secret>
```

## Global Flags

* `--json` or `--output json` for machine-readable output
* `--non-interactive` to disable prompts
* `--org <org>` to override the selected organization for one command
* `--token` to override the bearer token for one command