# How to Refresh the Tool Index on Linux or macOS: Complete Command Guide

> Easily refresh the tool index on Linux or macOS. Learn the complete command guide to regenerate markdown and JSON indexes. Run the script from your repository root.

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

---

**Run `bash skills/scripts/refresh-tool-index.sh` from the repository root to regenerate the markdown and JSON tool indexes on Linux or macOS.**

The **reverse-skill** repository by zhaoxuya520 provides a detection-only Bash script that scans your system for security tools, extracts their versions, and generates both human-readable and machine-readable indexes. This guide covers the exact command to refresh the tool index on Linux or macOS, customization options, and what happens when you run it.

## The Refresh Command for Linux and macOS

The standard invocation uses Bash to execute the script located at [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh):

```bash
bash skills/scripts/refresh-tool-index.sh

```

This command is documented in the repository's **AGENTS.md** entry-point guide under the "首次使用前按平台运行" (run before first use on the platform) section, which lists the exact invocation for Linux/macOS platforms.

### What the Script Does

When executed, [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) performs three main operations:

1. **Platform detection** — Identifies whether the host is `linux` or `macos` (lines 21-25)
2. **Tool discovery** — Iterates the predefined `TOOLS` array, checking command availability, probing installation paths, and extracting version strings (lines 58-141)
3. **Index generation** — Writes output to [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) (lines 46-53 and 78-85)

## Customizing Output Paths

The script accepts optional positional arguments to redirect the generated indexes:

```bash

# Custom markdown and JSON output locations

bash skills/scripts/refresh-tool-index.sh /tmp/my-tool-index.md /tmp/my-tool-index.json

```

If omitted, the script uses default paths relative to the repository root.

## Understanding the Generated Output

After execution, the script prints a completion summary:

```

✅ Tool index refreshed
  markdown=skills/tool-index.md
  json=skills/tool-index.json
  platform=linux
  tools=38

```

The **markdown index** ([`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md)) contains a formatted table with columns:

- **Tool** — Command name
- **Skill** — Category in the reverse-skill taxonomy
- **Purpose** — Description of the tool's function
- **Available** — Whether the tool was detected (`yes`/`no`)
- **Path** — Filesystem location where found
- **Version** — Extracted version string
- **Source** — Detection method used
- **Install hint** — Platform-specific installation command

The **JSON index** ([`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json)) provides the same data in a structured format for programmatic consumption.

## Key Files in the Refresh Workflow

| File | Purpose | Location |
|------|---------|----------|
| [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) | Main detection and generation script | [Source](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) |
| [`AGENTS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md) | Entry-point documentation with platform commands | [Source](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md) |
| [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) | Generated markdown output | (created by script) |
| [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) | Generated JSON output | (created by script) |

## Running from Different Directories

To ensure proper path resolution, execute the script from the repository root or use an absolute path:

```bash

# From repository root (recommended)

bash skills/scripts/refresh-tool-index.sh

# From elsewhere with absolute path

bash /path/to/reverse-skill/skills/scripts/refresh-tool-index.sh

```

The script's platform detection logic automatically adapts its tool probes for Linux or macOS environments without requiring additional flags.

## Summary

- The command to refresh the tool index on Linux or macOS is `bash skills/scripts/refresh-tool-index.sh`
- The script auto-detects platform and scans for 38+ security tools
- Outputs generate at [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) by default
- Custom output paths accept two positional arguments: markdown path, then JSON path
- Documented in [`AGENTS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md) as the required first-use step

## Frequently Asked Questions

### Do I need to run the refresh command before using reverse-skill tools?

Yes. According to the [`AGENTS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md) documentation, you must run `bash skills/scripts/refresh-tool-index.sh` before first use to generate the tool index that other components depend on.

### Does the refresh command require root privileges?

No. The script runs detection-only and queries tool availability through standard command existence checks and version flags. It does not modify system state.

### Can I run this on Windows?

The script targets Linux and macOS specifically. Windows users should use WSL (Windows Subsystem for Linux) and execute the command within that environment.

### What happens if a tool is not installed?

The index marks it as `Available: no` with `Path: —` and `Version: —`, but includes an **Install hint** column with the appropriate package manager command (e.g., `apt: sudo apt install nmap` or `brew: brew install openjdk`).