core/apps/init/README.md

Core CLI

🧠 CORE - Contextual Observation & Recall Engine

A Command-Line Interface for setting up and managing the Core development environment.

Installation

npm install -g @redplanethq/core

Commands

core init

One-time setup command - Initializes the Core development environment with full configuration.

core start

Daily usage command - Starts all Core services (Docker containers).

core stop

Daily usage command - Stops all Core services (Docker containers).

Getting Started

Prerequisites

• Node.js (v18.20.0 or higher)
• Docker and Docker Compose
• Git
• pnpm package manager

Initial Setup

1. Clone the Core repository:

   git clone https://github.com/redplanethq/core.git
   cd core
   

2. Run the initialization command:

   core init
   

3. The CLI will guide you through the complete setup process:

Step 1: Prerequisites Check

• The CLI shows a checklist of required tools
• Confirms you're in the Core repository directory
• Exits with instructions if prerequisites aren't met

Step 2: Environment Configuration

• Copies .env.example to .env in the root directory
• Copies trigger/.env.example to trigger/.env
• Skips copying if .env files already exist

Step 3: Docker Services Startup

• Starts main Core services: docker compose up -d
• Starts Trigger.dev services: docker compose up -d (in trigger/ directory)
• Shows real-time output with progress indicators

Step 4: Database Health Check

• Verifies PostgreSQL is running on localhost:5432
• Retries for up to 60 seconds if needed

Step 5: Trigger.dev Setup (Interactive)

• If Trigger.dev is not configured:

  1. Prompts you to open http://localhost:8030
  2. Asks you to login to Trigger.dev
  3. Guides you to create an organization and project
  4. Collects your Project ID and Secret Key
  5. Updates .env with your Trigger.dev configuration
  6. Restarts Core services with new configuration

• If Trigger.dev is already configured:

  • Skips setup and shows "Configuration already exists" message

Step 6: Docker Registry Login

• Displays docker login command with credentials from .env
• Waits for you to complete the login process

Step 7: Trigger.dev Task Deployment

• Automatically runs: npx trigger.dev@v4-beta login -a http://localhost:8030
• Deploys tasks with: pnpm trigger:deploy
• Shows manual deployment instructions if automatic deployment fails

Step 8: Setup Complete!

• Confirms all services are running
• Shows service URLs and connection information

Daily Usage

After initial setup, use these commands for daily development:

Start Services

core start

Starts all Docker containers for Core development.

Stop Services

core stop

Stops all Docker containers.

Service URLs

After setup, these services will be available:

• Core Application: http://localhost:3033
• Trigger.dev: http://localhost:8030
• PostgreSQL: localhost:5432

Troubleshooting

Repository Not Found

If you run commands outside the Core repository:

• The CLI will ask you to confirm you're in the Core repository
• If not, it provides instructions to clone the repository
• Navigate to the Core repository directory before running commands again

Docker Issues

• Ensure Docker is running
• Check Docker Compose is installed
• Verify you have sufficient system resources

Trigger.dev Setup Issues

• Check container logs: docker logs trigger-webapp --tail 50
• Ensure you can access http://localhost:8030
• Verify your network allows connections to localhost

Environment Variables

The CLI automatically manages these environment variables:

• TRIGGER_PROJECT_ID - Your Trigger.dev project ID
• TRIGGER_SECRET_KEY - Your Trigger.dev secret key
• Docker registry credentials for deployment

Manual Trigger.dev Deployment

If automatic deployment fails, run manually:

npx trigger.dev@v4-beta login -a http://localhost:8030
pnpm trigger:deploy

Development Workflow

1. First time setup: core init
2. Daily development:
   • core start - Start your development environment
   • Do your development work
   • core stop - Stop services when done

Support

For issues and questions:

• Check the main Core repository: https://github.com/redplanethq/core
• Review Docker container logs for troubleshooting
• Ensure all prerequisites are properly installed

Features

• 🚀 One-command setup - Complete environment initialization
• 🔄 Smart configuration - Skips already configured components
• 📱 Real-time feedback - Live progress indicators and output
• 🐳 Docker integration - Full container lifecycle management
• 🔧 Interactive setup - Guided configuration process
• 🎯 Error handling - Graceful failure with recovery instructions

---

Happy coding with Core! 🎉