CLI reference

Install Hugsy, then run hugsy --help. Each subcommand also supports --help.

Commands

CLI commands
Command	Behavior
`hugsy list [query]`	List or search component names, categories, and animation techniques.
`hugsy info <name>`	Read source, usage, integration requirements, and accessibility behavior.
`hugsy init`	Create hugsy.json. Use --directory to select the destination.
`hugsy add <names...>`	Copy one or more components, verifying integrity and preserving local edits.
`hugsy diff <names...>`	Read the installed and registry versions without changing files.
`hugsy doctor`	Validate configuration and explain iOS target integration.
`hugsy mcp`	Start the local, read-only MCP server over stdio.
`hugsy mcp-config`	Print portable MCP host configuration.

Plan before writing

init and add accept --dry-run. Adding components preflights the entire batch and refuses conflicts before copying anything. Only use --force after inspecting the local changes.

Terminal

hugsy list --json\nhugsy info expanding-cards --json\nhugsy add expanding-cards --dry-run --json

Automation

Data commands accept --json and --cwd <directory> after the subcommand. Runtime failures in JSON mode produce a structured error on stderr. Exit status is zero on success and nonzero on failure. Invalid command syntax uses the standard argument parser diagnostics.

The registry is compiled into the executable. Commands do not fetch remote source, run installation scripts, collect telemetry, or modify Xcode project files.

Interrupted installations

Cooperating installers share a lock. Handled write failures roll back changed files, but process termination or a disk failure can interrupt a batch. Inspect your project after interruption. Remove a stale .hugsy-install.lock only after confirming no installer is running.