CLI FAQ

Frequently asked questions and common issues with the Consuelo CLI.

Answers to the most common questions about the Consuelo CLI.

Installation

What Node.js version do I need?

Node.js 18 or later. Check your version:

node --version

If you have an older version, upgrade via nodejs.org or use nvm:

nvm install 20
nvm use 20

“consuelo: command not found”

The CLI isn’t in your PATH. Solutions:

1. Install globally:

   npm install -g @consuelo/cli
   

2. Check npm global bin is in PATH:

   npm bin -g
   # Add output to your shell profile (e.g., ~/.zshrc, ~/.bashrc)
   export PATH="$PATH:$(npm bin -g)"
   

3. Use npx instead:

   npx @consuelo/cli init
   

Can I use yarn instead of npm?

Yes:

yarn global add @consuelo/cli

Phone Numbers

Why does my phone number fail validation?

All phone numbers must be in E.164 format: +<country><number>

Format	Valid?	Example
[phone]	✓	Correct E.164
5551234567	✗	Missing + prefix
[phone]	✗	Contains spaces/parentheses
[phone]	✗	Contains dashes

Fix: Always include + and remove all formatting characters.

How do I format international numbers?

Use the country code with + prefix:

Country	Code	Example
US/Canada	+1	[phone]
UK	+44	[phone]
Germany	+49	[phone]
Australia	+61	[phone]
France	+33	[phone]

Can I use contact names instead of phone numbers?

Yes. Use the contact ID:

consuelo calls start contact_abc123

The CLI looks up the phone number automatically.

Commands

”Not implemented” error

Some commands return 501 Not Implemented because the feature is still in development. Check the phase roadmap for implementation status:

Feature	Status
Basic calling	✓ Implemented
Transfers	✓ Implemented
Queue management	✓ Implemented
Contacts API	Phase 4 (in progress)
History & Analytics	Phase 5 (in progress)
Knowledge Base	Phase 6 (in progress)

The CLI is under active development. Features are released as phases are completed.

How do I see all available commands?

consuelo --help
consuelo contacts --help
consuelo calls --help

Can I run commands non-interactively?

Yes, use --yes for defaults:

consuelo init --managed --yes

Or use JSON output for scripting:

consuelo contacts list --json | jq '.[] | .id'

Configuration

Where is config stored?

Scope	Path
Global	~/.consuelo/config.json
Project	./consuelo.config.json

Can I have multiple configurations?

Yes, use project configs:

cd project-a
consuelo config set workspaceId workspace-a

cd ../project-b
consuelo config set workspaceId workspace-b --scope project

How do I show sensitive values?

consuelo config get twilio.authToken --show-sensitive

Be careful showing sensitive values in shared terminals or screen shares.

Authentication

Which auth method should I use?

Method	Use When
OAuth (auth:login)	Regular use, CRM integration
API Key	Automation, CI/CD, scripts

Why does my token expire?

OAuth tokens expire after 24 hours. The CLI auto-refreshes, but if you haven’t used it in weeks, you may need to re-login:

consuelo auth:login

See Troubleshoot Auth for more.

Output

How do I get JSON output?

consuelo contacts list --json

How do I suppress output?

consuelo contacts delete contact_123 --quiet

Can I customize table columns?

Currently, table output uses default columns. Use --json and jq for custom formatting:

consuelo contacts list --json | jq -r '.[] | [.name, .phone] | @tsv'

Errors

”Rate limited” error

The API has rate limits. Wait a moment and retry:

# Wait 60 seconds, then retry
sleep 60 && consuelo contacts list

“Network error” / “Connection refused”

1. Check internet connection
2. Verify API URL:
   consuelo config get apiUrl
   
3. Try with verbose output:
   consuelo contacts list --verbose
   

“Permission denied”

You may not have access to the workspace or feature. Check:

consuelo status

Verify the correct workspace is set.

Deployment

Deploy fails with “Build error”

1. Check build logs:
   railway logs --build
   
2. Ensure dependencies install locally:
   yarn install
   
3. Verify Node version matches deployment target

”Database migration failed”

1. Check migration status:
   consuelo migrate status
   
2. Run migrations manually:
   consuelo migrate up
   
3. Rollback if needed:
   consuelo migrate down --steps 1
   

Worker not processing jobs

1. Verify worker is running:
   railway logs --service worker
   
2. Check Redis connection:
   consuelo status
   
3. Verify environment variables are set

Performance

CLI is slow on first run

First run loads dependencies. Subsequent runs are faster. If persistent:

# Check config validation
consuelo config validate

# Check network latency
ping consuelo.consuelohq.com

Import is slow for large CSVs

For 1000+ contacts:

• Use --quiet to reduce output
• Split into smaller files
• Import during off-peak hours

Getting Help

Where can I get support?

1. Check this FAQ and other docs
2. Run with --verbose for details
3. Check logs at ~/.consuelo/debug.log
4. Contact support with error details

How do I report a bug?

Include:

• CLI version: consuelo --version
• Command that failed
• Error message
• Steps to reproduce
• Config (redact sensitive values)

Is there a community?

Join the Consuelo community:

• GitHub: github.com/consuelohq/opensaas
• Discord: Available for customers

Next Steps

• Getting Started — Setup guide
• Configuration — Config reference
• Troubleshoot Auth — Auth issues