Command Reference

All available commands and options

Usage: hyphn [COMMAND] [OPTIONS]

Commands:
  init              Initialize ~/.hyphn directory structure
  setup             Configure integrations with AI tools
  serve             Start MCP server
  list              List available assets
  sources           Manage source repositories
  validate          Check assets for errors
  help              Show help message

init Command

Initialize the Hyph3n directory structure

Syntax

hyphn init [OPTIONS]

Options

Option Short Description
--force -f Overwrite existing configuration (creates backup first)
--yes -y Skip confirmation prompt (for scripting)
--minimal Create minimal structure without example assets
--json Output JSON (also skips confirmation prompts)

Examples

# First-time initialization
hyphn init

# Reinitialize (creates backup, prompts for confirmation)
hyphn init --force

# Reinitialize without prompt (for scripting)
hyphn init --force --yes

# Minimal structure (no examples)
hyphn init --minimal

# JSON output mode (also skips prompts)
hyphn init --json

Safety Features

setup Command

Configure OpenCode and Claude Code integrations

Syntax

hyphn setup [OPTIONS]

Description

The setup command configures your installed AI tools to recognize the Hyph3n directory structure:

Examples

# Configure all detected tools
hyphn setup

# Configure specific tool
hyphn setup --tool opencode
hyphn setup --tool claude-code

serve Command

Start MCP server for IDE integration

Syntax

hyphn serve [OPTIONS]

Options

Option Default Description
--port 3000 Port for MCP server
--host localhost Host for MCP server
--stdio false Use stdio transport instead of HTTP

Examples

# Start MCP server
hyphn serve

# Custom port
hyphn serve --port 8080

# Use stdio transport (for IDEs that require it)
hyphn serve --stdio

list Command

List available agents, commands, and skills

Syntax

hyphn list [TYPE]

Types

Type Description
agents List available agents
commands List available commands
skills List available skills
all List everything (default)

Examples

# List all assets
hyphn list

# List only agents
hyphn list agents

# List only skills
hyphn list skills

sources Command

Manage external source repositories

sources add

hyphn sources add  [OPTIONS]

Add a local directory or git repository as a source for agents, skills, and commands.

sources rm

hyphn sources rm

Remove a previously added source.

Examples

# Add team hyphn directory
hyphn sources add ~/team-hyphn

# Add company shared directory
hyphn sources add /shared/company/ai-config

# Add git repository
git clone https://github.com/my-org/ai-config.git ~/shared-config
hyphn sources add ~/shared-config

# Remove a source
hyphn sources rm ~/old-config

validate Command

Check assets for errors

Syntax

hyphn validate [OPTIONS]

Description

Validates all assets in ~/.hyphn for common errors:

Examples

# Validate all assets
hyphn validate

# Validate with detailed output
hyphn validate --verbose

Environment Variables

Configure hyphn behavior

Variable Default Description
HYPHN_HOME ~/.hyphn Primary directory for hyphn configuration and assets
HYPHN_PATH Additional sources (colon-separated paths)
HYPHN_NO_COLOR false Disable colored output (set to any value)

Examples

# Set custom hyphn home
export HYPHN_HOME="/opt/hyphn"
hyphn init

# Add multiple sources to path
export HYPHN_PATH="$HOME/team-hyphn:$HOME/company-hyphn"
hyphn list

# Disable colors
export HYPHN_NO_COLOR=1
hyphn list

File Structure

Understanding ~/.hyphn directory layout

Directory Layout

~/.hyphn/
├── agents/                 # Agent definitions
│   ├── my-agent.md
│   └── db-expert.md
├── commands/               # Custom slash commands
│   ├── deploy.sh
│   └── test.sh
├── skills/                # Reusable skills
│   ├── deployment/
│   └── database/
├── config/                # Configuration files
│   ├── config.yaml
│   └── hooks.yaml
├── sources/               # Source repository references
├── history/               # Session history (optional)
├── cache/                # Cached data (optional)
├── logs/                  # Log files (optional)
└── backups/               # Configuration backups
    └── config-{timestamp}/

Agent Format

# agents/db-expert.md
---
name: db-expert
description: Expert in PostgreSQL database operations
version: 1.0.0
---

You are a database expert specializing in PostgreSQL.

## Expertise

- Database schema design
- Query optimization
- Indexing strategies
- Migration planning

## Guidelines

- Always use parameterized queries to prevent SQL injection
- Consider indexing for frequently queried columns
- Test migrations on staging first
- Use transactions for multi-table operations

Skill Format

# skills/deployment/
---
name: deploy
description: Handle deployment workflows
triggers:
  - "deploy"
  - "ship it"
  - "production deployment"
---

## When to Use

Use this skill when you need to:
- Deploy to production
- Rollback a deployment
- Check deployment status

## Workflow

1. Run tests: npm test
2. Build application: npm run build
3. Deploy to staging
4. Verify staging deployment
5. Promote to production
6. Monitor production logs

Command Format

# commands/test.sh
#!/bin/bash
# Test command for project

echo "Running tests..."
bun test

echo "Running type checking..."
bun run typecheck

Hook System

Automate workflows with hooks

Configuration

Hooks are configured in ~/.hyphn/config/hooks.yaml:

# hooks.yaml
hooks:
  - event: pre-init
    command: echo "Initializing hyphn..."
  - event: post-init
    command: echo "Hyphn initialized successfully!"

Available Hooks

Event Description
pre-init Before initialization begins
post-init After initialization completes
pre-setup Before setup command runs
post-setup After setup command completes

Troubleshooting

Common issues and solutions

Configuration Not Found

If tools don't recognize hyphn assets:

# Re-run setup
hyphn setup

# Verify directory exists
ls -la ~/.hyphn

# Check tool config files
cat .claude/config.json
cat .opencode/config.json

Asset Not Loading

If an asset isn't showing up:

# Validate assets for errors
hyphn validate

# Check file permissions
ls -l ~/.hyphn/agents/

# Verify YAML frontmatter
cat ~/.hyphn/agents/my-agent.md

Source Not Found

# Check sources list
cat ~/.hyphn/config/sources.yaml

# Verify source path exists
ls -la ~/team-hyphn

# Re-add source
hyphn sources add ~/team-hyphn