Launchy AI

AI-powered CLI tool for setting up the Launchy iOS starter kit.

Installation

npm install -g launchy-ai

Or use directly with npx:

npx launchy-ai

Authentication

Before using Launchy AI, you need to authenticate with your API key:

launchy-ai login

You will be prompted to enter your API key. The key is saved locally at ~/.launchy-ai/config.json.

To logout:

launchy-ai logout

Usage

Interactive Mode

Start the interactive shell:

launchy-ai

Commands

| Command | Description | |---------|-------------| | login | Login with your API key | | logout | Logout and remove your API key | | setup | Start the interactive setup wizard | | doctor | Check your setup status | | ask <question> | Ask a question about Launchy | | help | Show available commands | | exit | Exit the shell |

Direct Commands

You can also run commands directly:

# Run the setup wizard
launchy-ai setup

# Check your setup status
launchy-ai doctor

# Ask a question
launchy-ai ask "How do I configure push notifications?"

Detailed Command Examples

login - Authentication

The login command prompts for your API key and validates it with the backend server.

$ launchy-ai login

╔═══════════════════════════════════════╗
║           LAUNCHY AI                  ║
╚═══════════════════════════════════════╝

Launchy AI Login

? Enter your API key: ********************************

✔ API key verified and saved

Login successful!

Email: [email protected]
Plan: standard
Config saved to: /Users/you/.launchy-ai/config.json

If already logged in:

$ launchy-ai login

Already logged in as [email protected]
Plan: standard

? Do you want to login with a different API key? (y/N)

setup - Interactive Setup Wizard

The setup command launches an interactive wizard to configure your Launchy project.

$ launchy-ai setup

════════════════════════════════════════
Starting Launchy Setup Wizard
════════════════════════════════════════

⠋ Initializing setup wizard...
✔ Setup wizard initialized

Welcome! I'll help you configure your Launchy project.

? What would you like to configure?
❯ Configure Firebase
  Configure RevenueCat
  Configure Environment Variables
  Run Doctor (check status)
  Exit Setup

Firebase Configuration:

? What would you like to configure? Configure Firebase

Firebase Configuration
════════════════════════════════════════
⠋ Checking Firebase configuration...
✔

Current status: GoogleService-Info.plist not found

? Do you have a Firebase project created? (y/N)

doctor - Diagnostics

The doctor command checks your project configuration and reports any issues.

$ launchy-ai doctor

════════════════════════════════════════
Running Launchy Doctor
════════════════════════════════════════

⠋ Checking your setup...
✔ Diagnostics complete

Local Checks:

  ✔ Node.js              v20.10.0 installed
  ✔ Launchy Project      Found in current directory
  ⚠ .env file            Not found - run setup to configure
  ⚠ Firebase (iOS)       GoogleService-Info.plist not found

Some warnings detected. Run "setup" to configure.

When all checks pass:

Local Checks:

  ✔ Node.js              v20.10.0 installed
  ✔ Launchy Project      Found in current directory
  ✔ .env file            Found
  ✔ Firebase (iOS)       GoogleService-Info.plist found

All checks passed! Your Launchy project is ready.

ask - Documentation Questions

Ask questions about the Launchy starter kit using AI-powered documentation search.

$ launchy-ai ask "How do I configure push notifications?"

════════════════════════════════════════
Question: How do I configure push notifications?
════════════════════════════════════════

⠋ Searching Launchy documentation...
✔ Found relevant information

To configure push notifications in Launchy:

1. Enable Push Notifications capability in Xcode
2. Configure Firebase Cloud Messaging (FCM)
3. Add the notification handler in App.tsx
...

Interactive Mode

Start the interactive shell for continuous interaction:

$ launchy-ai

╔═══════════════════════════════════════╗
║           LAUNCHY AI                  ║
╚═══════════════════════════════════════╝

Type 'help' for available commands, 'exit' to quit.

launchy> help

Available commands:
  setup   - Start the interactive setup wizard
  doctor  - Check your setup status
  ask     - Ask a question about Launchy
  help    - Show this help
  exit    - Exit the shell

launchy> ask How do I add a new screen?

⠋ Searching Launchy documentation...
...

launchy> exit

Goodbye!

Configuration

Launchy AI stores its configuration at:

~/.launchy-ai/config.json

Configuration File Structure

{
  "apiKey": "lai_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "email": "[email protected]",
  "plan": "standard"
}

| Field | Description | |-------|-------------| | apiKey | Your Launchy AI API key | | email | Email associated with the API key | | plan | Your subscription plan (standard or pro) |

Security

• The configuration directory is created with 0700 permissions (owner only)
• The config file is created with 0600 permissions (owner read/write only)
• API keys are stored locally and never transmitted except to the Launchy AI backend

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | LAUNCHY_AGENT_URL | Backend API URL | Production URL |

Example:

# Use local development server
export LAUNCHY_AGENT_URL="http://localhost:8000"
launchy-ai ask "How do I start?"

API Key

Your API key should be in the format: lai_ followed by 32 characters.

Example: lai_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Troubleshooting

Authentication Errors

"API key required" or "Invalid API key"

$ launchy-ai ask "question"
✖ Request failed: API key required

Solution: Run launchy-ai login to authenticate with your API key.

"Invalid API key format"

$ launchy-ai login
? Enter your API key: ********
✖ API key must start with "lai_"

Solution: Ensure your API key:

• Starts with lai_
• Is exactly 36 characters long

"Invalid or inactive API key"

$ launchy-ai login
? Enter your API key: ********************************
✖ Invalid API key
The API key you entered is invalid or inactive.

Solution:

• Verify you've entered the correct API key
• Contact support if you believe your key should be valid

Network Errors

"Request timeout" or "Network error"

$ launchy-ai ask "question"
✖ Search failed
Network error. Please check your connection.

Solution:

• Check your internet connection
• Verify the backend service is accessible
• If using a custom LAUNCHY_AGENT_URL, ensure the server is running

"Rate limit exceeded"

$ launchy-ai ask "question"
✖ Rate limit exceeded. Please try again later.

Solution: Wait 60 seconds before making more requests. The rate limit is 60 requests per minute.

Configuration Problems

"Not in a Launchy project directory"

$ launchy-ai doctor

⚠ Launchy Project      Not in a Launchy project directory

Solution: Navigate to your Launchy project directory before running commands:

cd /path/to/your/launchy-project
launchy-ai doctor

Config file corrupted

If the CLI behaves unexpectedly, try resetting the configuration:

# Remove the config file
rm ~/.launchy-ai/config.json

# Login again
launchy-ai login

General Debugging

Enable verbose logging by checking the request/response:

# Check if you're authenticated
cat ~/.launchy-ai/config.json

# Test the backend directly
curl -H "X-Launchy-API-Key: YOUR_API_KEY" \
  https://launchy-agent-5fmwg3aasa-an.a.run.app/health

Development Setup

This section is for contributors who want to modify or extend the CLI.

Prerequisites

• Node.js >= 18.0.0
• npm or yarn
• TypeScript knowledge

Project Structure

cli/
├── src/
│   ├── index.ts           # CLI entry point (Commander setup)
│   ├── repl.ts            # Interactive shell implementation
│   ├── api.ts             # Backend API client
│   ├── config.ts          # Configuration management
│   ├── commands/
│   │   ├── login.ts       # login/logout commands
│   │   ├── setup.ts       # Setup wizard
│   │   ├── doctor.ts      # Diagnostics
│   │   ├── ask.ts         # Documentation Q&A
│   │   └── help.ts        # Help display
│   └── utils/
│       ├── format.ts      # Terminal formatting helpers
│       └── spinner.ts     # Loading spinner utilities
├── package.json
├── tsconfig.json
└── README.md

Setting Up Development Environment

# Clone the repository
git clone <repository-url>
cd launchy-ai/cli

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Link for local testing
npm link

Running in Development

# Build and watch for changes
npm run dev

# Or build once
npm run build

# Run the CLI
node dist/index.js
# Or if linked:
launchy-ai

Adding a New Command

1. Create a new file in src/commands/:

// src/commands/mycommand.ts
import { formatInfo, printDivider } from '../utils/format.js';

export async function runMyCommand(): Promise<void> {
  console.log();
  printDivider();
  console.log(formatInfo('My Command'));
  printDivider();
  console.log();

  // Your command logic here
}

2. Register the command in src/index.ts:

import { runMyCommand } from './commands/mycommand.js';

program
  .command('mycommand')
  .description('Description of my command')
  .action(async () => {
    printHeader();
    await runMyCommand();
  });

3. Add to the REPL in src/repl.ts (if interactive support needed):

case 'mycommand':
  await runMyCommand();
  break;

4. Update the help command in src/commands/help.ts.

Local Backend Development

To test against a local backend server:

# Terminal 1: Start the backend
cd ../agent
source venv/bin/activate
python -m uvicorn app.main:app --reload --port 8000

# Terminal 2: Run CLI with local backend
export LAUNCHY_AGENT_URL="http://localhost:8000"
launchy-ai

Testing

# Run linting
npm run lint

# Type checking
npm run typecheck

# Build to verify no errors
npm run build

Building for Distribution

# Clean build
rm -rf dist/
npm run build

# Test the package locally
npm pack
npm install -g launchy-ai-0.1.0.tgz

# Publish to npm (maintainers only)
npm publish

Requirements

• Node.js >= 18.0.0

License

MIT