Alnilam CLI

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

Quick Start

# Install globally
npm install -g alnilam-cli

# Set up authentication
alnl auth login --email [email protected]

# 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)

npm install -g alnilam-cli

Local Installation

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:

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

# Optional for development
export [email protected]

Authentication

Alnilam uses Supabase authentication with magic links:

# Start authentication flow
alnl auth login --email [email protected]

# Check authentication status
alnl auth status

# For development/testing
alnl auth verify

Usage

Goal Management

# 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

# 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

# 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

# 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:

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:

# .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:

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

Configuration Options

CLI Configuration

# 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

alnl auth status
alnl auth verify  # Re-authenticate

Command Not Found

npm list -g alnilam-cli  # Check installation
npm install -g alnilam-cli  # Reinstall if needed

Network Errors

# Check environment variables
echo $SUPABASE_URL
echo $SUPABASE_ANON_KEY

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

Debug Mode

Enable debug logging:

DEBUG=alnilam:* alnl goal list

Development

Building from Source

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

Local Development

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 file for details.

Support

• 📚 Documentation
• 🐛 Report Issues
• 💬 Discussions

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