nerdcore 1.0.3

Nerd CLI is a Fivable-specific and highly configurable CLI tool for creating/running deployments, commands, and more.

nerdcore

Python framework for building CLI tools with commands, deployments, and entity management.

nerdcore provides the runtime, discovery, and utilities. Projects like nerdcli provide the actual command implementations.

Installation

# Editable install (development)
pip install -e ~/local-git/nerdcore

# Package install
pip install nerdcore

Concepts

Commands

Single-operation tools. Inherit from Command, declare arguments as class attributes, implement run().

from nerdcore.base_entities.command_class import Command

class MyCommand(Command):
    required_arg_keys = ['name']
    name: str = None

    def run(self):
        print(f"Hello, {self.name}")

Deployments

Multi-step orchestrations with config profile support. Inherit from Deployment.

from nerdcore.base_entities.deployment_class import Deployment

class MyDeploy(Deployment):
    app_name = 'myapp'
    required_config_keys = ['DEPLOY_TYPE']

    def run(self):
        # self.nerd_config has the loaded profile
        ...

Entity Discovery

Entities are Python files in commands/ and deployments/ directories. nerdcore discovers them by filename using fuzzy matching (Levenshtein distance). Running nerd deploy-lead finds deployments/deploy-lead.py.

Configuration

• NerdConfig: Singleton loaded from config/nerd-manifest.yaml. Profiles define deployment parameters.
• ENV: Environment variables loaded from .env via a project-specific env class.

Error Handling

• NerdUserError — user-facing errors (bad input, missing config). Clean message, no traceback.
• NerdError — internal errors. Message + traceback.

Both are defined in nerdcore.errors (import-free module to prevent circular dependencies).

Help System

nerdcore provides a dynamic, categorized help system:

• nerd help — Scans commands/ and deployments/ directories, extracts help_text and category from each entity class via ast.parse() (no imports needed), and displays a categorized listing.
• nerd help <command> — Imports the entity, reads class attributes (unnamed_arg_keys, named_arg_keys, required_arg_keys), type hints, defaults, and docstrings to display detailed per-command help.
• nerd list — All commands; nerd list --all includes nerdcore built-in commands.

Commands control their help output by setting class attributes: help_text, category.

Terminal Output

• print_t(message, style) — Themed output with emoji prefix and text wrapping. Use for operational messages.
• apply_t(text, color) — Returns a themed string without printing. Use with print() for structured output (help pages, tables) where you need precise formatting without emoji prefixes or wrapping.

Both are in nerdcore.utils.nerd.theme_functions.

Creating a New Project

After setup, nerd-new is available at .venv/bin/nerd-new:

.venv/bin/nerd-new my-project

This scaffolds the standard directory structure:

my-project/
├── abilities/
├── commands/
├── config/
│   └── framework/
├── deployments/
├── tasks/
├── stor/temp/
├── .env
├── .gitignore
├── requirements.txt
└── README.md

Entry Points

nerdcore registers three console_scripts via setup.py entry_points:

Command	Entry Point
nerd	nerdcore.cli.main:main
nerd-new	nerdcore.cli.nerd_new:main
nerdcore	nerdcore.__main__:main

Publishing

bump2version patch    # or minor, major
git push && git push --tags
# Triggers CI pipeline for PyPI publishing