CLI Reference

Global Options

These options apply to every hxc command:

hxc init

Initialize a new HoxCore registry in the specified directory.

hxc init [path] [OPTIONS]

Arguments

Options

Examples

# Initialize in the current directory
hxc init

# Initialize in a specific path
hxc init my-registry

# Skip Git setup entirely
hxc init ~/work-projects --no-git

# Initialize with a remote and skip the initial commit
hxc init . --remote https://github.com/user/registry.git --no-commit

# Initialize without setting this registry as the default
hxc init my-registry --no-set-default

hxc create

Create a new entity in the registry.

hxc create {program|project|mission|action} title [OPTIONS]

Arguments

Options

Examples

# Minimal project
hxc create project "New API"

# With custom ID and description
hxc create project "GraphQL Migration" --id P-042 -d "Migrate REST endpoints to GraphQL"

# Fully specified
hxc create project "GraphQL Migration" \
  --id P-042 \
  --category software.dev/api \
  --tags graphql migration backend \
  --parent prog_abc123 \
  --due-date 2024-12-31

# Create a mission from a template
hxc create mission "Q4 Launch" --template software.dev/cli-tool.default

# Target a specific registry
hxc create program "Platform Team" --registry ~/registries/work

# Skip commiting new project to git repository
hxc create project "GraphQL Migration" --id P-042 --no-commit

hxc delete

Delete an entity from the registry. The file is removed and the deletion is committed to Git.

hxc delete identifier [OPTIONS]

Arguments

Options

Examples

# Delete by ID (with confirmation prompt)
hxc delete P-001

# Delete by UID, skip confirmation
hxc delete a8bc123 --force

# Disambiguate when the same ID exists across types
hxc delete P-001 --type project

# Target a specific registry
hxc delete P-001 --force --registry ~/registries/work

# Delete without commiting to git
hxc delete P-001 --no-commit

hxc list

List entities in the registry.

hxc list [{program|project|mission|action|all}] [OPTIONS]

Arguments

Options

Examples

# List all projects (default type)
hxc list

# List all programs
hxc list program

# List active projects
hxc list project --status active

# Filter by tag (repeatable)
hxc list project --tag ai --tag python

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

# Filter by due date range and sort
hxc list project --before 2024-12-31 --sort due_date

# Output as JSON, limit to 10 results
hxc list all --format json --max 10

hxc show

Display the full details of a single entity.

hxc show identifier [OPTIONS]

Arguments

Options

Examples

# Show entity with default pretty formatting
hxc show P-001
hxc show proj_abc123def456

# Output as YAML or JSON
hxc show P-001 --format yaml
hxc show P-001 --format json

# Display raw file content
hxc show P-001 --raw

# Disambiguate type and target a specific registry
hxc show P-001 --type project --registry ~/registries/work

hxc edit

Edit properties of an existing entity. All changes are applied atomically and committed to Git.

hxc edit identifier [OPTIONS]

Arguments

General options

Scalar fields

Tags

Relationships

Integrations

Integration flags accept a JSON object string so that URLs with colons are never ambiguous. Each --add-* flag can be repeated multiple times in a single command to add several items at once.

Examples

# Set scalar fields (automatically creates a Git commit)
hxc edit P-001 --set-status completed --set-completion-date 2026-06-30

# Preview changes without saving or committing
hxc edit P-001 --set-title "Revised Title" --dry-run

# Update properties without creating a Git commit
hxc edit P-001 --add-tag "manual-update" --no-commit

# Tag operations
hxc edit P-001 --add-tag production --add-tag deployed
hxc edit P-001 --remove-tag wip
hxc edit P-001 --set-tags python cli backend

# Relationship operations
hxc edit P-001 --add-child proj_abc123 --add-related proj_def456

# Add a repository (JSON object — URLs with colons are handled correctly)
hxc edit P-001 --add-repository '{"name": "main", "url": "https://github.com/org/repo"}'

# Add multiple repositories in a single command
hxc edit P-001 \
  --add-repository '{"name": "main", "url": "https://github.com/org/main"}' \
  --add-repository '{"name": "docs", "url": "https://github.com/org/docs"}'

# Add a storage entry
hxc edit P-001 --add-storage '{"name": "assets", "provider": "gdrive", "url": "https://drive.google.com/drive/folders/abc"}'

# Add a database
hxc edit P-001 --add-database '{"name": "main", "type": "postgres", "url": "postgres://user:pass@host:5432/db"}'

# Add a tool
hxc edit P-001 --add-tool '{"name": "jira", "provider": "atlassian", "url": "https://org.atlassian.net"}'

# Add a model
hxc edit P-001 --add-model '{"id": "gpt-4", "provider": "openai", "url": "https://api.openai.com"}'

# Add a knowledge base
hxc edit P-001 --add-kb '{"id": "kb-docs", "url": "https://kb.example.com"}'

# Remove integration entries by name or ID
hxc edit P-001 --remove-repository legacy
hxc edit P-001 --remove-tool old-tracker

# Disambiguate type and target a specific registry
hxc edit P-001 --type project --registry ~/registries/work

hxc get

Retrieve a specific property value from an entity. Useful for scripting and piping output.

hxc get identifier property [OPTIONS]

Arguments

Options

Examples

# Get a scalar property
hxc get P-001 title
hxc get P-001 status

# Get all properties as YAML
hxc get P-001 all --format yaml

# Get a list property as JSON
hxc get P-001 tags --format json

# Get the first tag by index
hxc get P-001 tags --index 0

# Filter a complex list property by key
hxc get P-001 repositories --key name:github

# Disambiguate type and target a specific registry
hxc get P-001 title --type project --registry ~/registries/work

hxc registry

Manage registry locations.

hxc registry {path|list} [OPTIONS]

Subcommands

hxc registry path options

Examples

# Show the current registry path
hxc registry path

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

# List all known registries
hxc registry list

hxc validate

Validate registry integrity and consistency — checks required fields, UID uniqueness, relationships, status values, and entity types.

hxc validate [OPTIONS]

Options

Examples

# Validate the current or configured registry
hxc validate

# Show detailed output for each check
hxc validate --verbose

# Validate a specific registry
hxc validate --registry ~/registries/work

hxc mcp

Start the Model Context Protocol (MCP) server, giving compatible LLM clients — such as Claude Desktop — live read access to your registry.

hxc mcp [OPTIONS]

Options

Examples

# Start the MCP server using the default or configured registry
hxc mcp

# Start with a specific registry
hxc mcp --registry ~/registries/work

# Inspect available tools, resources, and prompts without starting
hxc mcp --capabilities

# Start in read-only mode (write tools are not exposed to the LLM)
hxc mcp --read-only

# Read-only with explicit registry
hxc mcp --registry ~/registries/work --read-only

{
  "mcpServers": {
    "hoxcore": {
      "command": "hxc",
      "args": ["mcp", "--registry", "/path/to/your/registry"]
    }
  }
}