HX One CLI

Professional command-line tool for Line 6 HX One guitar effects pedal

Control your HX One directly from your computer via USB MIDI. Switch presets, toggle effects, check device status, and manage preset files - all from the terminal.

⚠️ Disclaimer

This is a community-developed tool provided as-is without warranty. While it uses standard MIDI commands documented in the Line 6 HX One manual, use at your own risk. Always maintain backups of your presets.

This tool is not affiliated with, endorsed by, or supported by Line 6 or Yamaha Guitar Group. Line 6 and HX One are trademarks of their respective owners.

Tested on HX One firmware v3.83

Features

• MIDI Control - Control HX One via USB MIDI connection
• Preset Navigation - Switch between presets instantly
• Effect Toggle - Turn effects on/off remotely
• Device Status - Query device information and state
• Preset Files - Parse, compare, and analyze .hx1p preset files
• Fast & Reliable - Built with TypeScript, thoroughly tested
• Clean Output - Human-readable by default, JSON available

Quick Start

Prerequisites

• HX One connected via USB
• Node.js 18+ or Bun 1.0+
• macOS, Linux, or Windows

Installation

Install globally using npm or bun:

# Using npm
npm install -g @shadr/hx1-cli

# Using bun
bun install -g @shadr/hx1-cli

Verify Installation

hx1 --version

Basic Usage

# Check if device is connected
hx1 status

# Navigate presets
hx1 next          # Next preset
hx1 prev          # Previous preset
hx1 load 42       # Load preset #42

# Control effect
hx1 toggle        # Toggle effect on/off (emulates footswitch)
hx1 flux          # Activate FLUX (momentary effect variation)

Commands

The CLI has two types of commands: Device Control (requires HX One connected) and Preset Files (works offline).

Device Control

These commands require an HX One connected via USB.

hx1 status

Display device connection status and information.

$ hx1 status
HX One Status:

  Device:        HX One
  Connection:    USB MIDI
  MIDI Channel:  1

✓ Device connected and ready

Options:

• --json - Output in JSON format for scripting

$ hx1 status --json
{
  "connected": true,
  "device": {
    "name": "HX One",
    "connection": "USB MIDI"
  }
}

hx1 load <preset>

Load a specific preset by number (0-127).

$ hx1 load 10
✓ Loaded preset 010

$ hx1 load 0
✓ Loaded preset 000

Arguments:

• <preset> - Preset number (0-127)

Errors:

• Invalid preset number (out of range)
• Device not connected

hx1 next

Navigate to the next preset.

$ hx1 next
✓ Next preset loaded

hx1 prev

Navigate to the previous preset.

$ hx1 prev
✓ Previous preset loaded

hx1 toggle

Toggle the effect on/off (emulates pressing the footswitch).

$ hx1 toggle
✓ Effect toggled

Important: CC#1 emulates the footswitch, which toggles the effect state. It does NOT set an absolute on/off state. This means:

• If effect is currently OFF, it turns ON
• If effect is currently ON, it turns OFF
• Your script must track state if you need to know current status

hx1 flux

Activate the FLUX function (momentary effect variation).

$ hx1 flux
✓ FLUX activated

What is FLUX? FLUX is a momentary effect variation feature on HX One. The specific behavior depends on the current effect - it might create a dramatic parameter shift, momentary feedback, or other creative variation. Typically used as a momentary/held effect during performance.

Use cases:

• Add dramatic effect variations during performance
• Create momentary feedback or delay trails
• Trigger effect-specific special behaviors

Preset Files

These commands work with .hx1p preset files offline (no device required).

hx1 info <file>

Display detailed information about a preset file.

$ hx1 info "presets/70s Chorus.hx1p"

Preset Information:

  File:        presets/70s Chorus.hx1p
  Name:        70s Chorus
  Effect ID:   500 (0x1F4)
  Data Size:   165 bytes
  Parameters:  20

Parameters:

  Idx  Type       Value
  ───  ─────────  ──────────────
    0  Float      0.600000
    1  BoolOrIndex  0
    2  Float      0.400000
    ...

Use cases:

• Inspect preset files before loading
• Identify effect types
• View parameter values
• Debug preset issues

hx1 compare <file1> <file2>

Compare two preset files and show differences.

$ hx1 compare "preset1.hx1p" "preset2.hx1p"

Preset Comparison:

  File 1: preset1.hx1p
  File 2: preset2.hx1p

  Name 1: My Clean Tone
  Name 2: My Clean Tone V2
          ✗ Different names

  Effect 1: 500 (0x1F4)
  Effect 2: 500 (0x1F4)
            ✓ Same effect

Parameter Summary:

  Total:       20
  Same:        18
  Different:   2

Different Parameters:

  Idx  Type       Value 1        Value 2
  ───  ─────────  ─────────────  ─────────────
    0  Float      0.600000       0.750000
    2  Float      0.400000       0.500000

Use cases:

• Find what changed between preset versions
• Compare your settings to factory presets
• Track preset modifications over time
• Understand parameter differences

Scripting Examples

# Quick preset sequence for live performance
hx1 load 5 && sleep 30 && hx1 load 10 && sleep 45 && hx1 load 15

# Toggle effect on/off
hx1 toggle && sleep 2 && hx1 toggle

# Check connection before loading preset
if hx1 status --json | jq -e '.connected'; then
  hx1 load 42
fi

# Loop through presets (bash)
for i in {0..10}; do
  hx1 load $i
  sleep 5
done

# Compare two preset files
hx1 compare "original.hx1p" "modified.hx1p"

# Inspect preset before loading
hx1 info "presets/my-tone.hx1p"

Troubleshooting

Device Not Found

✗ HX One not found

💡 Make sure:
   • HX One is connected via USB
   • Device is powered on
   • USB cable is working

Solutions:

1. Check USB connection
2. Try a different USB port
3. Restart HX One
4. Check MIDI permissions (macOS)
5. List available MIDI devices: hx1 status --json

Permission Denied (macOS)

On macOS, you may need to grant MIDI access:

1. System Settings → Privacy & Security → MIDI Devices
2. Allow Terminal (or your terminal app)
3. Restart terminal

Commands Hang or Don't Exit

If commands don't return to prompt:

1. Press Ctrl+C to abort
2. Check for MIDI conflicts (close HX Edit, other MIDI software)
3. Restart the device

Invalid Preset Number

✗ Invalid preset number: 200 (must be 0-127)

HX One supports presets 0-127 only. Use numbers in this range.

Roadmap

Version 1.x

• ✅ MIDI device control
• ✅ Preset navigation
• ✅ Effect on/off toggle
• ✅ Device status query
• ⏳ Preset file commands (list, info, compare)
• ⏳ Configuration file support

Future

• Upload presets via MIDI
• Download presets from device
• Batch preset operations
• Preset library management
• Parameter editing

Have other ideas? Suggest them!

MIDI Implementation

The CLI uses standard MIDI messages to communicate with HX One:

• Program Change (PC 0-127) - Select preset
• Control Change CC#72 - Navigate presets
  • Value 0 = Previous
  • Value 64 = Next
• Control Change CC#1 - Toggle effect on/off
  • Emulates pressing the ON footswitch (toggles state)
  • Does NOT set absolute on/off state
  • Any value triggers a toggle
• Control Change CC#2 - Activate FLUX
  • Momentary effect variation
  • Behavior varies by effect type

All communication happens on MIDI Channel 1 by default.

Preset File Format

HX One uses .hx1p files for individual presets:

• Size: 1440 bytes (fixed)
• Format: Little-endian binary
• Contains: Effect ID, parameters, preset name

File Structure

Offset   Description
------   -----------
0x10     Effect Model ID (e.g., 500 = 70s Chorus)
0x14     Data size
0x18     Parameters (8 bytes each)
0x584    Preset name (null-terminated string)

For complete technical details, see docs/file-format.md.

Development

Local Development Setup

To use hx1 as a command during development (instead of bun run dev):

# Clone repository
git clone https://github.com/shad/hx-one.git
cd hx-one

# Install dependencies
bun install

# Build and link globally
bun run build
bun link

# Now you can use 'hx1' directly
hx1 --version
hx1 status

# After making changes, rebuild and the command updates automatically
bun run build

The hx1 command will point to /Users/yourusername/.bun/bin/hx1 and use your local development version.

Unlink when done:

bun unlink

Building from Source

# Install dependencies
bun install

# Run tests
bun run test

# Build
bun run build

# Run without linking
bun run dev status

Project Structure

hx-one/
├── src/
│   ├── cli/           # CLI commands
│   ├── core/          # Business logic
│   ├── services/      # MIDI & file services
│   └── types/         # TypeScript types
├── tests/
│   ├── unit/          # Unit tests
│   ├── integration/   # Integration tests
│   └── fixtures/      # Test data
└── docs/              # Documentation

For development guidelines, see CLAUDE.md.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure all tests pass: bun run check-all
5. Submit a pull request

See CLAUDE.md for code standards and architecture guidelines.

Technical Details

• Language: TypeScript (strict mode)
• Runtime: Node.js 18+ / Bun 1.0+
• MIDI Library: easymidi
• CLI Framework: Commander.js
• Testing: Vitest (95 tests, 82% coverage)
• Architecture: Layered (CLI → Services → Core)

For detailed documentation:

• CLI Specification - Complete command reference
• MIDI Overview - MIDI implementation details
• File Format - Binary format documentation
• Research Notes - Reverse engineering process

License

MIT License - see LICENSE for details.

Support

• Issues: GitHub Issues
• Discussions: HX One Forums

Built with ❤️ for the HX One community

Quick Reference

# Device Control (requires HX One connected)
hx1 next                    # Next preset
hx1 prev                    # Previous preset
hx1 load <0-127>            # Load specific preset
hx1 toggle                  # Toggle effect on/off
hx1 flux                    # Activate FLUX (momentary effect)
hx1 status                  # Device status
hx1 status --json           # JSON output

# Preset Files (offline)
hx1 info <file>             # Show preset details
hx1 compare <f1> <f2>       # Compare presets

# General
hx1 --help                  # Show help
hx1 --version               # Show version