CLI Command Reference
Relevant source files
The following files were used as context for generating this wiki page:
The projects-cli is a specialized command-line utility built with the Commander.js framework and the Bun runtime. Its primary purpose is to manage the metadata and deployment lifecycle of projects within the pcstyle.dev ecosystem. The tool automates project discovery, metadata extraction via Google Gemini AI, and synchronization with the central projects.json database.
The CLI acts as the administrative bridge between local development directories and the live portfolio site. It handles complex tasks such as technology stack normalization against a canonical list and automated deployment triggers upon successful data synchronization.
Sources: projects-cli/src/index.ts:1-12, projects-cli/package.json:1-20
Command Architecture and Core Logic
The CLI is structured into discrete command modules located in projects-cli/src/commands/. Each command utilizes a shared library for project data handling, AI analysis, and configuration management.
Command Execution Flow
The following diagram illustrates the typical lifecycle of a command execution, specifically focusing on the add and update --auto flows which involve external AI integration.
The CLI uses ensureGeminiKey to verify authentication before proceeding with data-intensive tasks.
Sources: projects-cli/src/commands/add.ts:15-111, projects-cli/src/utils/config.ts
Detailed Command Reference
Project Initialization: add <dirname>
The add command performs an automated analysis of a target directory to create a new entry in the portfolio. It prioritizes specific files like README.md, package.json, and Cargo.toml to build a 4000-character context window for the Google Gemini API.
| Step | Action | Description |
|---|---|---|
| 1 | Directory Access | Verifies the existence of the provided dirname. |
| 2 | File Gathering | Scans for priority configuration files and secondary source files. |
| 3 | AI Analysis | Sends file content and directory signals (extensions, structure) to Gemini. |
| 4 | Normalization | Maps detected technologies to the canonical stack list. |
| 5 | Output | Generates a .proj file in the local directory and updates projects.json. |
Sources: projects-cli/src/commands/add.ts:15-111, projects-cli/src/lib/gemini.ts:51-120
Content Management: update <name>
The update command allows for manual or AI-assisted modification of existing project records.
- Field-Level Update: Users can target specific fields using the
-f, --field <field>option (e.g.,status,stack,desc). - Auto-Update: Using the
--autoflag triggers the same Gemini analysis used in theaddcommand, comparing the AI's findings with existing data and proposing changes.
List and Filter: ls
The ls command provides a view of all registered projects. It supports filtering by status (active, maintenance, experimental, prototype, disabled).
Sources: projects-cli/src/index.ts:22-25
Data Models and Schemas
Project Metadata Schema
The CLI relies on a standardized Project interface and a ProjFile schema (used for local .proj files and AI responses).
| Field | Type | Description |
|---|---|---|
id | string | URL-friendly slug (lowercase, hyphens). |
name | string | Display name of the project. |
stack | string[] | Array of technologies used, normalized to the canonical list. |
status | ProjectStatus | One of: active, maintenance, experimental, prototype, disabled. |
icon | string | Lucide icon name. |
Sources: lib/types.ts:3-19, projects-cli/src/lib/gemini.ts:31-43
Stack Normalization
To maintain data integrity, the CLI uses a stack-canonical.json file to map various technology aliases to a standard label. For example, "NextJS" is automatically normalized to "Next.js".
AI Integration Logic
The CLI utilizes the gemini-2.5-flash model. It builds a context string by aggregating directory "signals" (file counts, top extensions, directory structure) and the content of key configuration files. Files exceeding 4000 characters are truncated to maintain token efficiency.
Signals Extraction
The buildSignals function extracts the following metadata to assist the AI:
- Extensions: Count of file types (e.g.,
.ts,.py). - Dependencies: Extracted from
package.json,requirements.txt,Cargo.toml, orgo.mod. - Git Context: Remote origin URL from
.git/configto detect GitHub repositories.
Sources: projects-cli/src/lib/gemini.ts:143-228, projects-cli/src/lib/gemini.ts:258-274
Conclusion
The projects-cli serves as the primary administrative tool for the pcstyle.dev ecosystem, leveraging Bun and Gemini AI to ensure project metadata is accurate, normalized, and synchronized. By automating the extraction of technical stacks and descriptions directly from source code, it minimizes manual entry errors and ensures the portfolio remains a high-fidelity representation of the developer's work.