CLI Reference

Overview

The HoxCore CLI (hxc) provides a comprehensive command-line interface for managing your project registry. All commands follow a consistent pattern and support both interactive and non-interactive modes.

Command Structure

hxc [global-options] <command> [command-options] [arguments]

Getting Help

# General help
hxc --help

# Command-specific help
hxc <command> --help

# Show version
hxc --version

# Bash
eval "$(hxc completion bash)"

# Zsh
eval "$(hxc completion zsh)"

Global Options

These options can be used with any command:

Examples

# Use specific registry
hxc --registry /path/to/registry list projects

# JSON output
hxc --format json show P-001

# Verbose mode
hxc -v create project --title "New Project"

init

Initialize a new HoxCore registry.

Syntax

hxc init [PATH] [options]

Arguments

Options

Examples

# Initialize in current directory
hxc init .

# Initialize in new directory
hxc init my-registry

# Initialize with name and description
hxc init my-registry \
  --name "My Projects" \
  --description "Personal project registry"

# Initialize without Git
hxc init my-registry --no-git

# Force overwrite existing registry
hxc init my-registry --force

Output

✅ Registry initialized at: /path/to/my-registry
📁 Created directory structure
🔧 Initialized Git repository
📝 Created config.yml
✨ Registry ready to use!

create

Create a new entity (program, project, mission, or action).

Syntax

hxc create <type> [options]

Entity Types

• program - Abstract container grouping related initiatives
• project - Object-like effort with concrete outputs
• mission - Event-like effort with clear culmination
• action - Ongoing activity without defined end

Common Options

Examples

# Basic project creation
hxc create project --title "My Project"

# Project with full details
hxc create project \
  --title "AI-Powered CLI Tool" \
  --description "Building an intelligent CLI" \
  --id P-001 \
  --category software.dev/cli-tool \
  --tags cli,ai,python \
  --start-date 2024-01-01 \
  --due-date 2024-12-31

# Create with template
hxc create project \
  --title "Python CLI Tool" \
  --template software.dev/cli-tool.python

# Create with parent
hxc create project \
  --title "Backend API" \
  --parent prog_abc123def456

# Interactive creation
hxc create project --interactive

# Create program
hxc create program \
  --title "Digital Transformation" \
  --description "Company-wide digital initiative"

# Create mission
hxc create mission \
  --title "Product Launch" \
  --due-date 2024-06-30

# Create action
hxc create action \
  --title "Weekly Team Meeting" \
  --description "Recurring team sync"

Output

✅ Project created successfully!
UID: proj_abc123def456
ID: P-001
Title: AI-Powered CLI Tool
Location: /path/to/registry/projects/proj_abc123def456.yml

📝 Entity definition saved
🔧 Template applied (if specified)
✨ Ready to use!

list

List entities in the registry.

Syntax

hxc list [type] [options]

Entity Types

• programs - List all programs
• projects - List all projects
• missions - List all missions
• actions - List all actions
• all - List all entities (default)

Options

Examples

# List all projects
hxc list projects

# List active projects
hxc list projects --status active

# List by category
hxc list projects --category software.dev

# List by tags
hxc list projects --tags ai,cli

# List with sorting
hxc list projects --sort due_date

# List with limit
hxc list projects --limit 10

# Detailed list
hxc list projects --long

# Tree view
hxc list all --tree

# List children of a program
hxc list projects --parent prog_abc123def456

Output

UID                    ID      Title                    Status    Category
proj_abc123def456      P-001   AI-Powered CLI Tool      active    software.dev/cli-tool
proj_xyz789ghi012      P-002   Backend API              active    software.dev/api
proj_mno345pqr678      P-003   Frontend App             on-hold   software.dev/web

Total: 3 projects

Tree View Output

Program: Digital Transformation (prog_abc123)
├── Project: AI-Powered CLI Tool (proj_def456)
│   ├── Mission: Launch v1.0 (miss_ghi789)
│   └── Action: Weekly Standup (act_jkl012)
└── Project: Backend API (proj_mno345)
    └── Mission: API v2 Release (miss_pqr678)

show

Display detailed information about an entity.

Syntax

hxc show <identifier> [options]

Arguments

Options

Examples

# Show by UID
hxc show proj_abc123def456

# Show by ID
hxc show P-001

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

# Show with history
hxc show P-001 --history

# Show with relationships
hxc show P-001 --relationships

# Show file path
hxc show P-001 --path

Output

═══════════════════════════════════════════════════════════
Entity Details
═══════════════════════════════════════════════════════════

UID:          proj_abc123def456
ID:           P-001
Type:         project
Title:        AI-Powered CLI Tool
Description:  Building an intelligent command-line interface
              with LLM integration and declarative templates.

Status:       active
Category:     software.dev/cli-tool
Tags:         cli, ai, python, tools

Dates:
  Created:    2024-01-01T10:00:00Z
  Modified:   2024-01-15T14:30:00Z
  Start:      2024-01-01
  Due:        2024-12-31

Hierarchy:
  Parent:     prog_xyz789ghi012 (Digital Transformation)
  Children:   2 entities

Integrations:
  Repositories:
    - github: https://github.com/user/repo
  
  Tools:
    - github-projects: https://github.com/user/repo/projects/1
  
  Models:
    - assistant (openwebui)

Location: /path/to/registry/projects/proj_abc123def456.yml

update

Update an existing entity.

Syntax

hxc update <identifier> [options]

Arguments

Options

Examples

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

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

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

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

# Remove tags
hxc update P-001 --remove-tags experimental

# Replace all tags
hxc update P-001 --set-tags production,stable,v1.0

# Update parent
hxc update P-001 --parent prog_xyz789

# Edit in text editor
hxc update P-001 --edit

# Update without committing
hxc update P-001 --status on-hold --no-commit

Output

✅ Entity updated successfully!
UID: proj_abc123def456
ID: P-001

Changes:
  status: active → completed
  completion_date: null → 2024-06-30
  tags: +finished, +successful

📝 Changes saved
🔧 Git commit created
✨ Update complete!

delete

Delete an entity from the registry.

Syntax

hxc delete <identifier> [options]

Arguments

Options

Examples

# Delete with confirmation
hxc delete P-001

# Delete without confirmation
hxc delete P-001 --force

# Delete with children
hxc delete prog_abc123 --recursive

# Delete without committing
hxc delete P-001 --no-commit

Output

⚠️  Warning: You are about to delete the following entity:

UID:   proj_abc123def456
ID:    P-001
Title: AI-Powered CLI Tool
Type:  project

This action cannot be undone (unless you restore from Git history).

Are you sure? [y/N]: y

✅ Entity deleted successfully!
📝 File removed
🔧 Git commit created
✨ Deletion complete!

query

Perform advanced searches across the registry.

Syntax

hxc query [type] [options]

Options

Examples

# Full-text search
hxc query --search "machine learning"

# Search by tags (AND)
hxc query --tags ai,cli,python

# Search by tags (OR)
hxc query --any-tags ai,ml,data

# Complex query
hxc query projects \
  --status active \
  --category software.dev \
  --tags ai \
  --due-before 2024-12-31

# Date range query
hxc query projects \
  --start-after 2024-01-01 \
  --due-before 2024-12-31

# Category wildcard
hxc query --category "software.*"

# Top-level entities only
hxc query --no-parent

# Entities with children
hxc query --has-children

# Recent modifications
hxc query --modified-after 2024-01-01 --sort modified

# Overdue projects
hxc query projects \
  --status active \
  --due-before $(date +%Y-%m-%d)

Output

Query Results (5 matches)
═══════════════════════════════════════════════════════════

UID                    ID      Title                    Status    Category
proj_abc123def456      P-001   AI-Powered CLI Tool      active    software.dev/cli-tool
proj_xyz789ghi012      P-002   ML Pipeline              active    software.dev/ml
proj_mno345pqr678      P-003   Data Analysis Tool       active    software.dev/data

Total: 3 projects matching query

registry

Manage registry locations and settings.

Subcommands

• path - Get or set the registry path
• list - List all known registries
• info - Show registry information
• validate - Validate registry structure

registry path

# Get current registry path
hxc registry path

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

registry list

# List all known registries
hxc registry list

registry info

# Show registry information
hxc registry info

# Show info for specific registry
hxc registry info --registry /path/to/registry

registry validate

# Validate current registry
hxc registry validate

# Validate specific registry
hxc registry validate --registry /path/to/registry

Examples

# Set default registry
hxc registry path --set ~/projects/my-registry

# View current registry
hxc registry path

# Show registry info
hxc registry info

# Validate registry
hxc registry validate

Output (registry info)

Registry Information
═══════════════════════════════════════════════════════════

Name:        my-registry
Version:     0.1.0
Path:        /home/user/projects/my-registry
Created:     2024-01-01T00:00:00Z

Statistics:
  Programs:  5
  Projects:  23
  Missions:  8
  Actions:   12
  Total:     48 entities

Git:
  Branch:    main
  Commits:   156
  Remote:    origin (https://github.com/user/my-registry.git)

Last Modified: 2024-01-15T14:30:00Z

template

Manage templates for entity scaffolding.

Subcommands

• list - List available templates
• show - Show template details
• create - Create a new template
• validate - Validate a template

template list

# List all templates
hxc template list

# List templates by category
hxc template list --category software.dev

template show

# Show template details
hxc template show software.dev/cli-tool.python

template create

# Create new template
hxc template create my-template \
  --category software.dev/custom \
  --description "My custom template"

template validate

# Validate template
hxc template validate my-template

Examples

# List all templates
hxc template list

# Show Python CLI template
hxc template show software.dev/cli-tool.python

# Create custom template
hxc template create my-cli-template \
  --category software.dev/cli-tool.custom

# Validate template
hxc template validate my-cli-template

export

Export entities to various formats.

Syntax

hxc export [options]

Options

Examples

# Export all to JSON
hxc export --format json --output registry.json

# Export projects to CSV
hxc export --type projects --format csv --output projects.csv

# Export active projects to Markdown
hxc export \
  --type projects \
  --filter "--status active" \
  --format markdown \
  --output active-projects.md

# Export with children
hxc export \
  --type programs \
  --include-children \
  --format yaml \
  --output programs-full.yml

import

Import entities from external sources.

Syntax

hxc import <file> [options]

Arguments

Options

Examples

# Import from JSON
hxc import projects.json

# Import with dry run
hxc import projects.json --dry-run

# Import and update existing
hxc import projects.json --update-existing

# Import from CSV
hxc import projects.csv --format csv

validate

Validate entity definitions and registry structure.

Syntax

hxc validate [identifier] [options]

Options

Examples

# Validate single entity
hxc validate P-001

# Validate all entities
hxc validate --all

# Validate all projects
hxc validate --type projects

# Strict validation
hxc validate --all --strict

# Validate and fix
hxc validate --all --fix

Output

Validation Results
═══════════════════════════════════════════════════════════

✅ proj_abc123def456 (P-001): Valid
⚠️  proj_xyz789ghi012 (P-002): Warning - Missing due_date
❌ proj_mno345pqr678 (P-003): Error - Invalid category format

Summary:
  Valid:    1
  Warnings: 1
  Errors:   1
  Total:    3 entities validated

config

Manage HoxCore configuration settings.

Subcommands

• get - Get configuration value
• set - Set configuration value
• list - List all configuration
• reset - Reset to defaults

config get

# Get specific value
hxc config get registry_path

# Get all values
hxc config get --all

config set

# Set value
hxc config set registry_path /path/to/registry

# Set multiple values
hxc config set auto_commit true
hxc config set default_category software.dev

config list

# List all configuration
hxc config list

config reset

# Reset all to defaults
hxc config reset

# Reset specific key
hxc config reset registry_path

Examples

# View current registry path
hxc config get registry_path

# Set auto-commit
hxc config set auto_commit true

# List all settings
hxc config list

# Reset to defaults
hxc config reset

Common Configuration Keys

Exit Codes

HoxCore uses standard exit codes to indicate command success or failure:

Environment Variables

HoxCore respects the following environment variables:

Examples

# Set default registry
export HXC_REGISTRY=/path/to/registry

# Set editor
export EDITOR=vim

# Disable colors
export NO_COLOR=1

Next Steps

Now that you're familiar with the CLI commands, explore more advanced features: