Alnilam CLI

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


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

$3

`bash
npm install -g alnilam-cli
`

$3

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

$3

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

Configuration

$3

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
`

$3

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

$3

`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
`

$3

`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 --type commit --message "Fixed authentication bug"

View evidence timeline

alnl evidence list
alnl evidence list --goal-id
`

$3

`bash


Generate daily summaries

alnl summary generate
alnl summary list
alnl summary view

Weekly evaluation

alnl evaluate

Get AI planning suggestions

alnl plan
`

$3

`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

$3

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 }}"}'
`

$3

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

$3

`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
`

$3

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

$3

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/"
`

$3

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

Development

$3

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

$3

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

Support

- 📚 Documentation
- 🐛 Report Issues
- 💬 Discussions

---

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