Getting Started

Install and configure the consuelo CLI in minutes.

Get up and running with the consuelo CLI in just a few minutes.

Prerequisites

Before installing the CLI, ensure you have:

• Node.js 18+ — Check with node --version
• npm or yarn — Package manager for installation
• Twilio account — For making calls (hosted) or Twilio credentials (self-hosted)
• Git — For deployment features

Self-hosted deployments also require Docker for local database setup.

Installation

Install the CLI globally via npm:

npm install -g @consuelo/cli

Or with yarn:

yarn global add @consuelo/cli

Verify the installation:

consuelo --version

Initial Setup

Run the interactive setup wizard:

consuelo init

The wizard will guide you through configuration based on your deployment type.

Hosted Setup (Recommended)

Choose Hosted (Mercury) when prompted. This uses Consuelo’s cloud infrastructure:

1. The CLI will prompt for authentication
2. A browser window opens for OAuth login
3. Complete login and return to the terminal
4. The CLI saves your credentials automatically

Self-Hosted Setup

Choose Self-hosted when prompted. This sets up local infrastructure:

1. Database setup — Choose Docker PostgreSQL or provide an existing connection string
2. Twilio credentials — Enter your Account SID, Auth Token, and phone number
3. AI provider — Enter your Groq or OpenAI API key
4. Optional Whisper model — Download for local transcript analysis (~75MB)

The wizard generates:

• .env file with your credentials
• docker-compose.yml for local services

Non-Interactive Setup

For CI/CD or automation, use --yes for defaults:

consuelo init --managed --yes

Available options:

Flag	Description
--managed	Use hosted infrastructure
--yes	Non-interactive with sensible defaults
--template <name>	Project template: full, minimal, api-only

Authentication

The CLI supports two authentication methods:

Consuelo SDK Auth (OAuth)

For CRM integration and full platform access:

consuelo auth:login

This opens a browser for OAuth authentication. After login, credentials are stored securely and refreshed automatically.

API Key Auth

For direct API access without OAuth:

Set the API key via environment variable:

export CONSUELO_API_KEY=your_api_key_here

Or add to your config:

consuelo config set apiKey your_api_key_here

For multi-tenant workspaces, also set:

export CONSUELO_WORKSPACE_ID=your_workspace_id

API keys are sensitive. Never commit them to version control. Use environment variables or the CLI’s secure config storage.

Verify Your Setup

Check that everything is configured correctly:

consuelo status

This displays:

• Configuration file location
• Twilio credentials status
• AI provider status
• Database connection (self-hosted)
• API connectivity

Configuration Files

The CLI stores configuration in two locations:

Scope	Path	Purpose
Global	~/.consuelo/config.json	User-wide settings, credentials
Project	./consuelo.config.json	Project-specific overrides

Project config overrides global config, allowing different settings per workspace.

Next Steps

• Configuration — Learn about config options
• Contact Management — Import and manage contacts
• Call Operations — Make your first call
• Troubleshooting Auth — Fix common auth issues