crush-commands

Install Crush commands from GitHub repositories.

Installation

No installation required! Just use npx:

npx crush-commands <owner>/<repo> --command <name>

Usage

Install All Commands

Install all commands from a repository:

npx crush-commands add <owner>/<repo>

Example:

npx crush-commands add myuser/my-crush-commands

Install a Specific Command

Install a specific command by name:

npx crush-commands <owner>/<repo> --command <name>

Example:

npx crush-commands myuser/my-crush-commands --command mycommand

Options

• --command, -c <name> - Install a specific command (without .md extension)
• --ref <branch|tag> - Use specific branch or tag (default: default branch)
• --yes, -y - Skip confirmation prompts (useful for CI/automation)
• --quiet, -q - Suppress non-essential output
• --help, -h - Show help message
• --version, -v - Show version number

Examples

Install all commands from the main branch:

npx crush-commands add myuser/my-crush-commands --ref main

Install a specific command without confirmation:

npx crush-commands myuser/my-crush-commands --command mycommand --yes

Install commands quietly (for scripts):

npx crush-commands add myuser/my-crush-commands --quiet

How It Works

1. The tool fetches the crush/commands/ directory from the target GitHub repository
2. It lists all .md files in that directory
3. For each command file, it checks if it already exists in ~/.crush/commands
4. If a file exists, it asks for confirmation before overwriting (unless --yes is used)
5. It writes the command files to ~/.crush/commands/<name>.md

Repository Structure

The tool expects repositories to have the following structure:

my-repo/
└── crush/
    └── commands/
        ├── command1.md
        ├── command2.md
        └── command3.md

Each .md file should contain a Crush command definition.

Requirements

• Node.js 18 or higher
• Internet connection to access GitHub's public API
• The target repository must be public and contain a crush/commands/ directory

Limitations

• Only works with public GitHub repositories
• Only installs .md files from crush/commands/ directory
• Requires write permissions to ~/.crush/commands
• GitHub API rate limits apply (60 requests/hour for unauthenticated requests)

After Installation

After installing commands, run:

crush reload

This refreshes Crush's command cache so the new commands are available.

Error Handling

The tool provides helpful error messages for common issues:

• Repository not found: Verify the repository exists and is public
• No commands found: Check that the repository has a crush/commands/ directory with .md files
• Network errors: Check your internet connection
• Rate limit exceeded: Wait before trying again

License

MIT