Getting Started

Prerequisites

Before installing HoxCore, ensure you have the following:

• Python 3.8 or higher
• pip — Python package installer
• Git — required for version control features

python --version
# Python 3.8+ required

Installation

Standard installation

pip install hoxcore

Install from source

git clone https://github.com/sdescobedo/hoxcore.git
cd hoxcore
pip install -e .

Development dependencies

pip install hoxcore[dev]

# Create and activate
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install hoxcore

Verify Installation

hxc --version
hxc --help

You should see:

hxc version 0.1.0

Initialize a Registry

A registry is a dedicated Git repository containing only YAML metadata. Think of it as a Git repository for your project definitions.

# Initialize in a new directory
hxc init my-registry

# Or in the current directory
hxc init .

Registry Structure

my-registry/
├── .git/           # Git repository
├── .hxc/           # HoxCore internal data
├── config.yml      # Registry configuration
├── programs/       # Program definitions
├── projects/       # Project definitions
├── missions/       # Mission definitions
├── actions/        # Action definitions
└── templates/      # Custom templates

Create a Project

# Minimal
hxc create project "My First Project"

# With details
hxc create project \
  "AI-Powered CLI Tool" \
  --description "Building an intelligent command-line interface" \
  --category software.dev/cli-tool \
  --id P-001 \
  --tags cli ai python \
  --due-date 2024-12-31

HoxCore automatically assigns an immutable UID (e.g. abc123def456), sets the status to active, and creates a YAML file in projects/.

List Entities

hxc list project
hxc list program
hxc list all

# Filter
hxc list project --status active
hxc list project --category software.dev/cli-tool
hxc list project --tags cli,ai,python

TTYPE    ID       TITLE               STATUS
-------------------------------------------
project P-001    AI-Powered CLI Tool active
project d6e80843 My First Project    active

View Entity Details

# By UID or ID
hxc show d6e80843
hxc show P-001

# Show raw YAML
hxc show P-001 --raw

# Show as json
hxc show P-001 --format json

Update an Entity

# Update status
hxc edit P-001 --set-status completed

# Multiple fields
hxc edit P-001 \
  --set-status completed \
  --set-completion-date 2024-06-30 \
  --add-tag finished \
  --add-tag experimental

# Tag management
hxc edit P-001 --add-tag production
hxc edit P-001 --remove-tag experimental

Query Entities

# Full-text search in title and description
hxc list --query "AI-Powered"

# Tag filters
hxc list --tag production


# Overdue projects
hxc list project --status active 

Set Registry Path

# Set default registry
hxc registry path --set /path/to/my-registry

# View current registry
hxc registry path

Next Steps