# How to Run the Master-Route Script on Linux or macOS: Complete Command Guide

> Run the master-route script on Linux or macOS easily. Discover the exact command to execute the router from your terminal with our comprehensive guide.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-31

---

**Use `bash skills/scripts/master-route.sh --hint "<task description>"` to execute the router from any Linux or macOS terminal.**

The **master-route script** is the primary entry point in the `zhaoxuya520/reverse-skill` repository for driving the routing engine. Located at [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh), this Bash wrapper parses command-line arguments, locates the routing configuration, and invokes an embedded Python engine to evaluate your task hint against predefined routing rules.

## Command Syntax and Required Flags

The script accepts several flags to control its behavior. Only `--hint` is mandatory.

| Flag | Aliases | Purpose |
|------|---------|---------|
| `--hint` | `-Hint`, `-hint` | **Required.** The task description used to match against routing rules |
| `--out-dir` | — | Optional. Custom directory for the generated [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) output |
| `--project-root` | — | Optional. Alternative path to treat as the project root |

The parsing logic lives at lines 10–24 of [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh), which normalizes flag names before processing.

## Basic Usage Examples

Run the master-route script with a simple task hint:

```bash
bash skills/scripts/master-route.sh --hint "enumerate open ports"

```

This command:
1. Loads the routing table from [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) (lines 31–38)
2. Evaluates the hint against available skills via embedded Python (lines 54–68)
3. Prints a summary (primary skill, confidence score, notes)
4. Writes [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) to the default output directory

## Advanced Invocation Patterns

### Custom Output Directory

Redirect the generated scope report to a specific folder:

```bash
bash skills/scripts/master-route.sh \
     --hint "collect credential hashes" \
     --out-dir /tmp/my-route-output

```

The `--out-dir` flag overrides the default location where [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) is written.

### Alternative Project Root

When using the repository as a dependency in another project, specify a different root:

```bash
bash skills/scripts/master-route.sh \
     --hint "analyze malware sample" \
     --project-root /home/user/my-analysis-project

```

This tells the script to resolve [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) relative to the provided path rather than the script's own directory.

## How the Script Works Internally

According to the `zhaoxuya520/reverse-skill` source code, [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) performs three core operations:

- **Argument normalization** (lines 10–24): Converts `-Hint` or `-hint` variants to the canonical `--hint` form
- **Environment setup** (lines 31–38): Discovers the routing table and locates a Python 3 interpreter
- **Routing execution** (lines 54–68 and beyond): Embeds and executes Python code that matches your hint to skills, calculates confidence scores, and generates the route report

The embedded Python engine outputs structured data that downstream skills consume to determine which capabilities to activate.

## Platform Compatibility Notes

The script uses **POSIX-compliant Bash** constructs tested on:
- Linux distributions (Ubuntu, Debian, Fedora, Arch)
- macOS (Intel and Apple Silicon)

No additional dependencies are required beyond Python 3, which the script auto-detects in your environment.

## Summary

- **Primary command**: `bash skills/scripts/master-route.sh --hint "<description>"`
- **Required flag**: `--hint` (or `-Hint`/`-hint`) to specify your task
- **Optional flags**: `--out-dir` for custom output, `--project-root` for dependency usage
- **Key files**: [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) (entry point), [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) (routing rules)
- **Output**: Console summary plus [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) report for downstream processing

## Frequently Asked Questions

### What happens if I omit the `--hint` flag?

The script will fail with a usage error. Lines 10–24 of [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) enforce that `--hint` must be provided, as the routing engine requires a task description to match against available skills.

### Can I run the script without the `bash` prefix?

Yes, if you first make the script executable with `chmod +x skills/scripts/master-route.sh`. Then run `./skills/scripts/master-route.sh --hint "<task>"`. The `bash` prefix shown in examples ensures cross-platform consistency regardless of file permissions.

### Where does the routing logic actually execute?

Inside an embedded Python block (lines 54–68 of [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)). The Bash wrapper handles argument parsing and environment setup, then passes control to Python for the actual hint evaluation against [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json).

### What Python version is required?

The script locates any available Python 3 interpreter (lines 31–38). No specific minor version is enforced, though Python 3.6+ is recommended for full compatibility with the embedded routing logic.