Skip to main content

​
About auggie cloud

Cosmos 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.
Running auggie cloud with no arguments prints the available command groups. Each group has its own help, and so does each command within it.
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 to get them.

​
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 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: The workflow is init → edit → validate → diff → apply.
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:
1

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.
2

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.
3

Apply on merge

Run apply from CI on merge to your default branch, authenticated as a service account. The repository becomes the source of truth for your Cosmos configuration.
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.
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