Cosmic CLI

Product Introduction

1. Definition: The Cosmic CLI is an AI-powered command-line interface (CLI) tool designed for developers working with the Cosmic headless CMS platform. It functions as a terminal-based development environment, integrating interactive shells, AI agents, and deployment orchestration directly within the command line.
2. Core Value Proposition: It exists to eliminate context switching between the terminal, CMS dashboard, and deployment platforms. Its primary value is collapsing complex content and application development workflows—including AI-generated content creation, code generation, repository management, and Vercel deployment—into single, natural language commands, drastically accelerating development cycles.

Main Features

1. Interactive Shell (cosmic shell): Launches a persistent terminal session with filesystem-like navigation (cd, ls, pwd) for Cosmic projects, buckets, and object types. Enables direct execution of Cosmic commands (e.g., objects list) without the cosmic prefix and system commands via ! (e.g., !git status). Uses context-aware prompts and maintains command history.
2. AI Chat Modes (cosmic chat): Provides context-aware conversational AI interfaces for specific tasks:
   • --content: Modifies Cosmic content objects using natural language prompts.
   • --build: Generates complete application codebases (e.g., "A recipe blog with search").
   • --repo: Updates existing code repositories (e.g., "Add dark mode").
   • Accepts contextual flags (--types, --links) to ground AI responses. Leverages models like Claude, GPT, or Gemini.
3. Filesystem-Style Navigation: Models Cosmic's hierarchical structure (Workspaces > Projects > Buckets > Object Types) as a virtual filesystem. Commands like cosmic cd my-project and cosmic ls enable intuitive exploration and context setting, mirroring local directory navigation.
4. Full Repository Management (cosmic repos): Manages GitHub integration end-to-end: clones repositories with auto-configured environment variables (cosmic repos clone), creates branches (branches create), generates pull requests (pr create), merges PRs (pr merge), manages environment variables (env create), and configures custom domains (domains create).
5. Multi-Model AI Integration (cosmic models, cosmic config): Supports switching between leading AI providers (Anthropic's Claude, OpenAI's GPT, Google's Gemini). Users can list available models (cosmic models), set a default (config set defaultModel claude-opus-4-5-20251101), or override per-command (ai generate --model=gpt-5).

Problems Solved

1. Pain Point: Fragmented Development Workflows. Traditional headless CMS usage requires constant switching between terminal (coding), browser (CMS dashboard for content/modeling), and deployment platforms, causing inefficiency.
2. Target Audience:
   • Full-Stack Developers: Building content-driven apps (Next.js, Astro, etc.) who need integrated content/code/deployment workflows.
   • DevOps Engineers: Automating CI/CD pipelines involving CMS content updates or schema changes.
   • Technical Content Managers: Needing to batch-create or update structured content programmatically.
3. Use Cases:
   • Rapid Prototyping: Generating a functional app with AI-created content and deploying it in minutes (cosmic build -p "...", cosmic deploy).
   • Automated Content Pipelines: Scheduling AI agents via CLI to generate weekly content summaries (cosmic agents create --type content --schedule-frequency weekly).
   • Legacy Code Modernization: Adding features like dark mode to existing repos using AI (cosmic update my-repo -p "Add dark mode").

Unique Advantages

1. Differentiation: Unlike basic CMS API wrappers or standalone AI coding tools, the Cosmic CLI integrates AI agents directly into the terminal workflow for both content and code, coupled with deployment and repo management. Competitors lack this unified, agent-driven CLI environment.
2. Key Innovation: The context-aware AI shell that understands Cosmic's data model (objects, types, buckets) and codebase structures simultaneously. This allows natural language commands like cosmic content -p "Create 5 recipes with images" or cosmic update ... -p "Add favorites feature" to execute complex, multi-step operations involving schema validation, API calls, and code generation without manual intervention.

Frequently Asked Questions (FAQ)

1. How do I install the Cosmic CLI? Install it globally via npm (npm install -g @cosmicjs/cli) or Bun (bun add -g @cosmicjs/cli), then authenticate using cosmic login for full access or cosmic use --bucket=... for bucket-specific access.
2. Can I use the Cosmic CLI for free? Yes, the Free plan includes CLI access with basic AI agent limits (2 agents/project) and token usage; scheduled agents and higher limits require Starter plan or higher.
3. How does the Cosmic CLI handle deployment? It integrates directly with Vercel via cosmic deploy start <repoId> --watch, managing environment variables, custom domains, previews, production releases, and real-time log streaming without manual Vercel configuration.
4. Is my existing Cosmic project compatible with the CLI? Yes, use cosmic use to select your workspace/project. The CLI operates on your existing Cosmic data and schemas. Use cosmic update to modify existing project codebases.
5. How does the CLI compare to the Cosmic dashboard? The CLI provides terminal-centric access to all dashboard capabilities (content, objects, models, agents, deployments) plus advanced automation, scripting, and AI-driven workflows unsuitable for a GUI, making it essential for developers and automation.