CLI Quickstart

The Cosmo CLI gives you full access to Cosmo from the terminal — chat with AI, manage workspaces, use connected tools, and generate artifacts without leaving your workflow.

Prerequisites

• Node.js 18+ (check with node --version)
• An active Cosmo account (sign up at cosmo.dev)

Step 1: Install

Install the CLI globally via npm:

npm install -g @cosmohq/cli

Verify the installation:

cosmo --version

If you see a version number, you're ready.

Step 2: Authenticate

Log in with your Cosmo account:

cosmo auth login

This opens your browser to complete authentication. After authorizing, return to the terminal — the CLI detects the completed login automatically and stores credentials securely.

To check your auth status at any time:

cosmo auth status

To log out:

cosmo auth logout

Step 3: Set Up a Team Workspace

Initialise a local team workspace directory:

cosmo team init

Check sync status with the cloud:

cosmo team status

To sync your local workspace with the cloud (once signed in):

cosmo team sync

The team workspace becomes the context for your AI conversations — it shapes what AI knows and where artifacts are stored.

Step 4: Start Chatting

Launch the interactive REPL:

cosmo

You'll see a prompt where you can type messages directly to AI:

cosmo > Tell me about this workspace
cosmo > Search the web for the latest on AI model context windows
cosmo > Create a project status document for our Q3 roadmap

The REPL supports:

• Multi-line input (press Shift + Enter for a new line, Enter to send)
• Real-time streaming responses
• Tool call visibility (you can see which tools AI is invoking)
• Artifact output (artifacts are saved to your workspace and can be exported)

To exit the REPL:

cosmo > /exit

Or press Ctrl + C.

Step 5: Run a One-Shot Command

For scripting or quick queries, send a message directly without entering the REPL:

cosmo chat -m "Summarize the last 5 commits in this repo"
cosmo chat -m "Create a draft proposal for expanding to the EU market"

Output streams to stdout, making it easy to pipe into other commands:

cosmo chat -m "List action items from the meeting notes" > action-items.md

Step 6: Connect Tools

Connect MCP integrations from the CLI:

cosmo mcp list                              # Show configured MCP servers
cosmo mcp connect google-drive --label Personal  # Connect Google Drive (opens OAuth)
cosmo mcp connect atlassian --label Work         # Connect Atlassian (opens OAuth)

Once connected, integrations are available in every REPL session and one-shot command.

Useful Commands

# Authentication
cosmo auth login               # Sign in
cosmo auth logout              # Sign out
cosmo auth status              # Check current auth state

# Team workspace
cosmo team init                # Initialise a local team workspace
cosmo team sync                # Sync with the cloud (push + pull)
cosmo team sync --push         # Push local changes only
cosmo team sync --pull         # Pull remote changes only
cosmo team status              # Show sync status

# Chat
cosmo                          # Open interactive REPL
cosmo chat -m "<message>"      # Send a one-shot message

# MCP integrations
cosmo mcp list                              # List configured MCP servers
cosmo mcp connect <server-type> --label <name>  # Connect an integration
cosmo mcp disconnect <instance-id>          # Disconnect an integration

# General
cosmo --help                   # Show help
cosmo <command> --help         # Help for a specific command
cosmo --version                # Show installed version

Configuration

The CLI stores its configuration in ~/.cosmo/. This includes:

• Authentication tokens (~/.cosmo/auth.json)
• MCP connection configs (~/.cosmo/mcp.json)
• Default workspace and preferences

You can inspect these files directly — they're plain JSON.

Environment Variables

Override settings via environment variables:

What's Next