trace-mapper

trace-mapper is a CLI tool designed to scan your codebase, map your API flows, and generate visual representations or structured JSON data.

Installation

You can run trace-mapper directly using npx (no installation required):

npx trace-mapper map

Or you can install it globally:

npm install -g trace-mapper

If installed globally, you can run:

trace-mapper map

Usage

Navigate to your project directory and run the map (or scan) command:

npx trace-mapper map [options]

Options

| Option | Description | Default | | ------ | ----------- | ------- | | -d, --dir <directory> | Directory to scan | Current working directory | | -k, --key <key> | API key for trace.dev. Saves to ~/.trace/config.json. | (reads from $TRACE_API_KEY) | | -n, --name <name> | Name for the mapped flow | | | --json | Output raw JSON data instead of formatted logs (useful for piping) | false | | --depth <number> | Max directory depth to traverse during the scan | 10 | | --include <globs> | Extra glob patterns to include (comma-separated) | | | --exclude <globs> | Extra ignore patterns to exclude (comma-separated) | | | --no-color | Disable color output in the terminal | |

Examples

Scan the current directory

npx trace-mapper map

Scan a specific directory with a custom name

npx trace-mapper map -d ./my-backend-service -n "Backend API Flow"

Output results as JSON and save to a file

npx trace-mapper map --json > api-flow.json

Set API key for trace.dev

npx trace-mapper map -k your_api_key_here

(Your key is saved to ~/.trace/config.json for future use).

Configuration

If you don't want to pass your API key via the CLI flag every time, you can also set it using the TRACE_API_KEY environment variable in your project's .env file or terminal environment.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the ISC License.

👨‍💻 Author

Parth Mongia

• GitHub: @Parth308
• Email: [email protected]
• Portfolio: parthmongia.dev

📮 Support

• 🐛 Report bugs
• 💡 Request features
• ⭐ Star on GitHub