Getting Started

Prerequisites

Before installing HoxCore, ensure you have the following:

• Python 3.8 or higher - HoxCore is built with Python
• pip - Python package installer (usually comes with Python)
• Git - Required for version control features
• Terminal/Command Line - Basic familiarity with command-line interfaces

python --version
# or
python3 --version

Installation

Install HoxCore using pip, Python's package manager:

Standard Installation

pip install hxc

Install from Source

If you want to install from the source repository:

# Clone the repository
git clone https://github.com/yourusername/hoxcore.git
cd hoxcore

# Install in development mode
pip install -e .

Install with Development Dependencies

For contributors who want to run tests and development tools:

pip install hxc[dev]

# Create virtual environment
python -m venv hxc-env

# Activate (Linux/Mac)
source hxc-env/bin/activate

# Activate (Windows)
hxc-env\Scripts\activate

# Install HoxCore
pip install hxc

Verify Installation

After installation, verify that HoxCore is correctly installed:

# Check version
hxc --version

# View help
hxc --help

You should see output similar to:

hxc version 0.1.0

Initialize a Registry

A registry is the central repository where HoxCore stores all your project metadata. Think of it as a Git repository for your project definitions.

Create a New Registry

# Initialize in a new directory
hxc init my-registry

# Or initialize in the current directory
hxc init .

This command creates a new registry with the following structure:

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

Registry Structure

Understanding the registry structure helps you navigate and manage your entities effectively.

Directory Organization

Configuration File

The config.yml file contains registry-wide settings:

# config.yml
registry:
  name: my-registry
  version: 0.1.0
  created: 2024-01-01T00:00:00Z

settings:
  default_category: general
  auto_commit: true
  index_on_change: true

integrations:
  github:
    enabled: false
  azure_devops:
    enabled: false

Create Your First Project

Let's create your first project in the registry:

Basic Project Creation

hxc create project \
  --title "My First Project" \
  --description "Learning HoxCore basics" \
  --category software.dev/cli-tool

This creates a new project with:

• Auto-generated UID (e.g., proj_abc123def456)
• Status set to active by default
• Current date as start date
• YAML file in projects/ directory

Project with More Details

hxc create project \
  --title "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

Interactive Creation

You can also create projects interactively:

hxc create project --interactive

List Entities

View all entities in your registry:

List All Projects

hxc list projects

Output example:

UID                    ID      Title                    Status    Category
proj_abc123def456      P-001   My First Project         active    software.dev/cli-tool
proj_xyz789ghi012      P-002   AI-Powered CLI Tool      active    software.dev/cli-tool

List Other Entity Types

# List programs
hxc list programs

# List missions
hxc list missions

# List actions
hxc list actions

# List all entities
hxc list all

Filter by Status

# List only active projects
hxc list projects --status active

# List completed projects
hxc list projects --status completed

Filter by Category

hxc list projects --category software.dev

View Entity Details

Display detailed information about a specific entity:

By UID

hxc show proj_abc123def456

By ID

hxc show P-001

Output example:

UID: proj_abc123def456
ID: P-001
Type: project
Title: My First Project
Description: Learning HoxCore basics
Status: active
Category: software.dev/cli-tool
Tags: [cli, learning, tutorial]
Created: 2024-01-01T10:00:00Z
Modified: 2024-01-01T10:00:00Z
Start Date: 2024-01-01
Due Date: 2024-12-31

Repositories: None
Storage: None
Tools: None
Models: None

View Raw YAML

hxc show P-001 --raw

Update an Entity

Modify existing entity properties:

Update Single Field

# Update status
hxc update P-001 --status completed

# Update title
hxc update P-001 --title "Updated Project Title"

# Add tags
hxc update P-001 --add-tags production,deployed

Update Multiple Fields

hxc update P-001 \
  --status completed \
  --completion-date 2024-06-30 \
  --add-tags finished,successful

Edit in Text Editor

# Opens the YAML file in your default editor
hxc update P-001 --edit

Query Entities

Perform advanced searches across your registry:

Query by Tags

# Find all entities with 'ai' tag
hxc query --tags ai

# Find entities with multiple tags (AND)
hxc query --tags ai,cli,python

Query by Date Range

# Projects starting in 2024
hxc query projects --start-after 2024-01-01

# Projects due before end of year
hxc query projects --due-before 2024-12-31

Complex Queries

# Active software projects with AI tag
hxc query projects \
  --status active \
  --category software.dev \
  --tags ai

Full-Text Search

# Search in title and description
hxc query --search "machine learning"

Set Registry Path

Configure HoxCore to use a specific registry by default:

Set Default Registry

hxc registry path --set /path/to/my-registry

View Current Registry

hxc registry path

Use Different Registry Temporarily

# Use --registry flag for one-time operations
hxc list projects --registry /path/to/other-registry

Next Steps

Now that you've learned the basics, explore more advanced features:

Quick Reference

Common commands for quick access: