Getting Started
Relevant Source Files
This page provides a technical guide for installing and configuring PALEE (Personal Active Learning & Evaluation Engine). It covers the global installation process, vault connection, and the configuration of AI providers.
Installation
PALEE is distributed as a global npm package. It requires Node.js ≥ 22planning/palee_cli_spec.md#9-14
npm install -g @kuldeep2822k/paleeUpon installation, the palee binary becomes available. The CLI uses standard exit codes for scripting: 0 for success, 2 for usage errors, and 4 for optimistic concurrency conflicts README.md#190-198
Sources:README.md#17-20planning/palee_cli_spec.md#9-14planning/palee_cli_spec.md#83
Initial Configuration
PALEE requires a connection to an Obsidian vault to function, as the vault serves as the canonical source of truth planning/palee_cli_spec.md#26-27
1. Connecting a Vault
The palee config set-vault <path> command validates that the provided path exists and is a directory before saving it to the global configuration src/cli/config.ts#63-84
palee config set-vault ~/Documents/Obsidian/Learning2. AI Provider Setup (Optional)
While PALEE's core engine is deterministic, advanced features like Feynman testing require an OpenAI-compatible API endpoint README.md#27-33
palee config set-provider "https://opencode.ai/zen/v1"
palee config set-model "nemotron-3-ultra-free"
# API Key is prompted or set via environment variables3. Verifying Configuration
Use palee config show to view the active configuration. For security, the api_key is never printed to the console src/cli/config.ts#54-61
Sources:src/cli/config.ts#52-121README.md#22-33planning/palee_cli_spec.md#77-79
Configuration Data Flow
The configuration is managed by the configCommand handler and persisted in a platform-specific config.json file.
Configuration Persistence Mapping
| Platform | Path |
|---|---|
| Windows | %LOCALAPPDATA%\palee\config.json |
| Unix/macOS | ~/.config/palee/config.json |
| Override | process.env.PALEE_CONFIG_DIR |
Sources:src/cli/config.ts#11-25README.md#199-203
Implementation Diagram: Configuration Logic
This diagram traces how configCommand interacts with the PaleeConfig interface and the file system.
Sources:src/cli/config.ts#52-121src/cli/config.ts#9src/types.ts#1-20
Adopting Your First Topic
Once configured, you must "adopt" existing Markdown files into the PALEE system. This process injects the necessary YAML frontmatter without destroying existing note content planning/palee_cli_spec.md#32-33
palee adopt "Docker Fundamentals.md" --difficulty beginnerThe Adoption Process
- Path Validation: The CLI ensures the file is within the configured vault and prevents path traversal test/cli-commands.test.ts#66-72
- Frontmatter Injection: The
updateFrontmatterutility addspalee_id,palee_schema, and initial SM-2 metrics (e.g.,ease_factor: 2.5) src/cli/review.ts#90-93planning/example_workflows.md#27-50 - Atomic Write: The system uses
atomicWritewith a SHA-256 fingerprint check to prevent overwriting concurrent manual edits in Obsidian src/cli/review.ts#91-93
Data Entity Relationship: CLI to Topic
This diagram shows how a CLI command transforms a standard Markdown file into a PALEE Topic entity.
Sources:src/cli/review.ts#38-54src/cli/review.ts#80-93src/storage/frontmatter.ts#1-50src/storage/atomic-write.ts#1-30
Summary of First Commands
| Command | Technical Action | Source |
|---|---|---|
palee next | Calculates the highest priority topic based on SM-2 due_at and dependency readiness. | README.md#100 |
palee plan | Aggregates a list of topics, filtering for satisfied prerequisites via areDependenciesSatisfied. | README.md#101 |
palee progress | Scans the vault via walkVault and aggregates topic_mastery across all tracks. | README.md#102 |
palee dashboard | Provides a high-level summary of vault health, including total topics and due reviews. | test/cli-commands.test.ts#166-173 |
Sources:README.md#96-116test/cli-commands.test.ts#166-188src/cli/review.ts#22-113