alnilam-cli/README.md

Git-native AI career coach that converts multi-year ambitions into weekly execution

# Alnilam CLI

> Git-native AI career coach that converts multi-year ambitions into weekly execution

[![npm version](https://badge.fury.io/js/alnilam-cli.svg)](https://badge.fury.io/js/alnilam-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)

## Quick Start

```bash
# Install globally
npm install -g alnilam-cli

# Set up authentication
alnl auth login --email your@email.com

# Create your first goal
alnl goal add --title "Launch my startup" --horizon quarterly

# Track evidence
alnl evidence add --type note --message "Completed market research"

# View your progress
alnl dashboard
```

## Features

🎯 **Smart Goal Management**
- Multi-horizon goals (weekly → quarterly → annual → multi-year)
- Automatic progress tracking and momentum scoring
- AI-powered weekly planning and adjustments

🤖 **AI-Powered Coaching**
- Daily evidence summarization with GPT-4.1 mini
- Weekly momentum evaluation (0-100 scoring)
- Strategic planning proposals with cost optimization

📊 **Rich Dashboards**
- Visual progress tracking with charts and sparklines
- Goal tree visualization and dependency mapping
- Evidence timeline and achievement celebrations

🔗 **Git Integration**
- Automatic commit and PR evidence collection
- Goal-based branch naming conventions
- GitHub Actions for seamless workflow integration

## Installation

### Global Installation (Recommended)

```bash
npm install -g alnilam-cli
```

### Local Installation

```bash
npm install alnilam-cli
npx alnl --version
```

### Requirements

- Node.js 18.0.0 or higher
- Git (for evidence collection)
- Internet connection (for AI features)

## Configuration

### Environment Setup

Create a `.env` file or set environment variables:

```bash
# Required for production use
export SUPABASE_URL=https://your-project.supabase.co
export SUPABASE_ANON_KEY=your-anon-key

# Optional for development
export TEST_EMAIL=your@email.com
```

### Authentication

Alnilam uses Supabase authentication with magic links:

```bash
# Start authentication flow
alnl auth login --email your@email.com

# Check authentication status
alnl auth status

# For development/testing
alnl auth verify
```

## Usage

### Goal Management

```bash
# Create goals
alnl goal add --title "Master TypeScript" --horizon quarterly
alnl goal add --title "Ship v1.0" --horizon weekly --target-date 2025-07-15

# List goals
alnl goal list                    # All goals
alnl goal list --horizon weekly   # Filter by horizon
alnl goal list --json            # JSON output

# View goal details
alnl goal view <goal-id>
```

### Evidence Tracking

```bash
# Add evidence manually
alnl evidence add --type note --message "Completed initial setup"
alnl evidence add --type time --message "3 hours of focused coding"

# Link evidence to specific goals
alnl evidence add --goal-id <id> --type commit --message "Fixed authentication bug"

# View evidence timeline
alnl evidence list
alnl evidence list --goal-id <id>
```

### AI Features

```bash
# Generate daily summaries
alnl summary generate
alnl summary list
alnl summary view <date>

# Weekly evaluation
alnl evaluate

# Get AI planning suggestions
alnl plan
```

### Dashboards & Analytics

```bash
# Interactive dashboard
alnl dashboard

# Simple status overview
alnl status

# Celebration mode (when goals completed)
alnl celebrate
```

## JSON Output

All commands support `--json` flag for programmatic use:

```bash
alnl goal list --json | jq '.[] | select(.horizon == "weekly")'
alnl auth status --json
alnl evaluate --json
```

## Git Integration

### Automatic Evidence Collection

Set up the GitHub Action for automatic evidence collection:

```yaml
# .github/workflows/alnilam-evidence.yml
name: Alnilam Evidence Collection
on: [push, pull_request]
jobs:
  collect-evidence:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Collect Evidence
        run: |
          curl -X POST "$SUPABASE_URL/functions/v1/add_evidence" \
            -H "Authorization: Bearer $SUPABASE_ANON_KEY" \
            -d '{"type": "commit", "message": "${{ github.event.head_commit.message }}"}'
```

### Goal-Based Branching

Use goal IDs in branch names for automatic linking:

```bash
git checkout -b goal/abc123/implement-authentication
git commit -m "Add JWT token validation"
# Evidence automatically linked to goal abc123
```

## Configuration Options

### CLI Configuration

```bash
# Production environment
export SUPABASE_URL=https://your-project.supabase.co
export SUPABASE_ANON_KEY=your-production-key

# Development environment  
export SUPABASE_URL=http://127.0.0.1:54321
export SUPABASE_ANON_KEY=your-dev-key
```

### Cost Management

AI features are optimized for cost efficiency:
- Daily summaries: ~$0.02 per day
- Weekly evaluations: ~$0.05 per week
- Planning sessions: ~$0.18 per week
- **Total weekly cost: < $0.25**

## Architecture

Alnilam is built on a modern, scalable architecture:

- **CLI**: TypeScript + Commander + Ink
- **Backend**: Supabase Edge Functions (Deno)
- **Database**: Postgres with pgvector for embeddings
- **AI**: OpenAI GPT-4.1 mini with function calling
- **Auth**: JWT tokens with magic link authentication

## Troubleshooting

### Common Issues

**Authentication Failed**
```bash
alnl auth status
alnl auth verify  # Re-authenticate
```

**Command Not Found**
```bash
npm list -g alnilam-cli  # Check installation
npm install -g alnilam-cli  # Reinstall if needed
```

**Network Errors**
```bash
# Check environment variables
echo $SUPABASE_URL
echo $SUPABASE_ANON_KEY

# Test connectivity
curl "$SUPABASE_URL/rest/v1/"
```

### Debug Mode

Enable debug logging:
```bash
DEBUG=alnilam:* alnl goal list
```

## Development

### Building from Source

```bash
git clone https://github.com/your-username/alnilam.git
cd alnilam/cli
pnpm install
pnpm build
```

### Local Development

```bash
pnpm dev goal list  # Run with tsx
pnpm start goal list  # Run compiled version
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- 📚 [Documentation](https://github.com/your-username/alnilam)
- 🐛 [Report Issues](https://github.com/your-username/alnilam/issues)
- 💬 [Discussions](https://github.com/your-username/alnilam/discussions)

---

**Ready to transform your ambitions into achievements? Start with `alnl goal add` today! 🚀**