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

# Managing Cosmos with auggie cloud

> Everything you can do in the Cosmos UI can also be done from the terminal. The auggie cloud command group is the CLI surface for the Cosmos control plane, so your Experts, environments, and sessions can be managed programmatically.

## About `auggie cloud`

[Cosmos](/cosmos/getting-started) resources such as Experts, environments, sessions, triggers, secrets, MCP servers, and Spaces are managed by a control plane that Auggie CLI talks to directly. The `auggie cloud` command group exposes that control plane in your terminal, so anything you would click through in the Cosmos web UI can also be scripted, reviewed, and automated.

```sh theme={null}
auggie cloud
```

Running `auggie cloud` with no arguments prints the available command groups. Each group has its own help, and so does each command within it.

```sh theme={null}
# List the command groups
auggie cloud --help

# List the commands in a group
auggie cloud expert --help

# See the flags for a single command
auggie cloud expert apply --help
```

<Note>
  The CLI is the source of truth for the current command set. Cosmos ships continuously, so use `--help` rather than a memorized list, as new groups and flags appear whenever the platform gains capabilities. Keep Auggie [up to date](/cli/autoupgrade) to get them.
</Note>

## API first

Cosmos is built API first. The web UI is a client of the same API that Auggie CLI calls, which means the CLI is never a partial mirror of the product. Creating an Expert, editing an environment, launching a session, or rotating a secret are the same operations regardless of which surface you use.

That has a few practical consequences:

* **Nothing is UI-only.** If you can configure it in Cosmos, you can configure it from a script, a CI job, or another agent.
* **Output is machine readable.** Most list and get commands accept `--json` so you can pipe results into `jq` or feed them to another tool.
* **Automation uses the same identity model.** Run `auggie cloud` from CI or a pipeline with a [service account](/cli/automation/service-accounts) token instead of a personal session.

## Declarative bundles

Resources that carry meaningful configuration, including Experts, environments, MCP servers, and residents, are represented as YAML **bundles**. A bundle is a complete, portable description of the resource, so it can live in a repository and be reviewed like any other change.

These resources share the same command shape:

| Command    | Description                                              |
| :--------- | :------------------------------------------------------- |
| `init`     | Scaffold a new bundle template                           |
| `export`   | Write an existing remote resource to a local bundle file |
| `validate` | Check a bundle without contacting the control plane      |
| `diff`     | Compare a local bundle against the remote resource       |
| `apply`    | Create or update the remote resource from the bundle     |

The workflow is `init` → edit → `validate` → `diff` → `apply`.

```sh theme={null}
# Start from a template, or export what already exists
auggie cloud expert init --name pr-author -o pr-author.yaml
auggie cloud expert export <expert-id> -o pr-author.yaml

# Check the bundle, then preview what would change remotely
auggie cloud expert validate -f pr-author.yaml
auggie cloud expert diff -f pr-author.yaml

# Apply it
auggie cloud expert apply -f pr-author.yaml
```

Every `apply` creates a new immutable version of the resource, so changes can be reviewed and rolled back. Use `auggie cloud expert versions <expert-id>` to see the history.

## GitOps workflows

Because bundles are files and `apply` is idempotent, you can manage your Cosmos configuration the same way you manage infrastructure: commit it, review it, and let CI reconcile it.

A typical setup looks like this:

<Steps>
  <Step title="Export your existing configuration">
    Run `export` for the Experts and environments you already have and commit the bundles to a repository. This gives you a reviewable baseline of how your agents are configured.
  </Step>

  <Step title="Validate on every pull request">
    Run `validate` on the changed bundles, then `diff` or `apply --dry-run`, so reviewers can see exactly what the merge would change in the control plane before approving it.
  </Step>

  <Step title="Apply on merge">
    Run `apply` from CI on merge to your default branch, authenticated as a [service account](/cli/automation/service-accounts). The repository becomes the source of truth for your Cosmos configuration.
  </Step>
</Steps>

```sh theme={null}
# In a pull request check
auggie cloud expert validate -f experts/pr-author.yaml
auggie cloud expert apply -f experts/pr-author.yaml --dry-run

# On merge to the default branch
auggie cloud expert apply -f experts/pr-author.yaml
```

<Note>
  Bundles include `metadata.resourceVersion` for optimistic concurrency. If an Expert may have been edited in the UI since you last exported it, re-export before applying rather than overwriting someone else's change.
</Note>

Beyond configuration, the same commands let you build workflows on top of Cosmos. Launch a session from an Expert as a pipeline step with `auggie cloud session create`, pause a noisy trigger with `auggie cloud trigger disable`, or pull usage data for reporting with `auggie cloud usage`.

## See Also

* [Cosmos Experts](/cosmos/experts): what Experts are and how they're configured
* [Cosmos Environments](/cosmos/environments/overview): where your agents run
* [Using Auggie with Automation](/cli/automation/overview): running Auggie in CI/CD
* [Service Accounts](/cli/automation/service-accounts): non-human identities for automation
* [CLI Reference](/cli/reference): complete command-line reference