How to create Security CLI tools using npx-cli + Claude Code

TL;DR: Install the npx-cli skill, define the dirscan CLI requirements, let Claude generate and implement the plan, then build and test the finished tool

Why create your own CLI tools

For visibility: a working tool gives people something they can run, not just read
For your portfolio: show that you can build security tooling and understand the workflow behind it

What is npx-cli

Main idea: skip the CLI boilerplate and get to a working scaffold faster
Eliminates boilerplate for command parsing, output formatting, and project structure

Setup

Before starting, set up these pieces:

Claude Code CLI installed and authenticated
Node.js 18+ and npm configured for package publishing (create an npm account first if you don't have one)
Basic familiarity with JavaScript and security tooling concepts

Step 1: Install the npx-cli skill

Run this command in your Claude Code session to add the skill:

npx skills add https://github.com/jwynia/agent-skills --skill npx-cli

If the install works, Claude Code will show the skill in your local registry

Step 2: Verify the skill installation

Run the skills list command to confirm npx-cli appears in your available skills:

/skills

Look for npx-cli in the list. If it is missing, rerun the install command and read the error before moving on

Step 3: Prepare your project context

Create a CLAUDE.md file in your new project directory. This file gives Claude the constraints. The more concrete you are, the less cleanup you usually do later

Example CLAUDE.md:

I need to build an npx-ready CLI tool called dirscan

Rules:
1. Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
2. Simplicity First
Minimum code that solves the problem. Nothing speculative.
3. Surgical Changes
Touch only what you must. Clean up only your own mess.
4. Goal-Driven Execution
Define success criteria. Loop until verified.

Use Case: Build dirscan - A web directory scanner

For the example, we'll build dirscan: a small web directory scanner. It checks a target for hidden paths. Boring recon work, but useful

Step 1: Define your product description

When the skill asks what you want to build, give it something like this:

name: dirscan
Directory scanning tool for discovering hidden paths and resources on web applications
Arguments:
- target URL (required)
- wordlist path (optional, defaults to a built-in common.txt wordlist)

This is enough to start the scaffold. You can bolt on more flags later

Step 2: Use the npx-cli prompt to generate the scaffold

Paste the npx-cli prompt into Claude Code, then add your tool description under it. Claude should return an implementation plan before it writes files

The template pushes Claude toward an npx-ready app instead of a loose Node script. You should get package metadata, a bin entry point, source files, and basic tests

The prompt template:

# Objective

Write a concise statement describing the primary goal of the product. Focus on the problem being solved and the value delivered to users. Avoid implementation details, technical architecture, or feature lists.

# Tasks

Generate a structured task breakdown required to build the product.

Requirements:

* Group tasks by major functional areas.
* Focus on what needs to be built, not how it should be implemented.
* Include only tasks that are directly related to the product description.
* Keep task names action-oriented and clear.
* Organize tasks from core functionality to supporting functionality.
* Exclude project management, deployment, marketing, and business-related tasks unless explicitly mentioned.
* Prioritize the smallest viable implementation that delivers the core value of the product.

# Implementation Context

The generated tasks, project scaffold, architecture recommendations, implementation guidelines, code generators, file structures, examples, and development workflow MUST assume the project is being built as an **NPX-first CLI application**.

Requirements:

* Always design the project as a command-line tool that can be installed and executed via `npx`.
* All scaffolding recommendations must follow modern Node.js CLI application conventions.
* All project structures must be optimized for CLI usability, maintainability, and distribution through npm.
* Any generated architecture should assume a standalone CLI product rather than a web application, desktop application, or API service unless explicitly stated in the product description.
* Any implementation plan should leverage existing `/npx-cli` skills, patterns, conventions, and best practices.
* Prefer simple command interfaces and minimal configuration.
* Design for a single executable entry point whenever practical.
* Keep dependencies minimal unless the product description requires otherwise.
* When generating project structures, include CLI-specific components such as:

  * executable entry point
  * command parser
  * output formatter
  * configuration handling (if required)
  * testing structure
* Do not generate scaffolds based on Python, Go, Rust, Java, web frameworks, or desktop frameworks unless explicitly requested.
* Treat the CLI experience as a first-class design requirement.

# Output Format

```markdown
# Objective

<single clear objective>

# Tasks

## Core Functionality
- Task 1
- Task 2

## Data Processing
- Task 1
- Task 2

## User Experience
- Task 1
- Task 2

## Supporting Features
- Task 1
- Task 2

# Recommended NPX CLI Scaffold

<project structure>

# CLI Considerations

<cli-specific recommendations>
```

Product Description:

Wait for user input the product description

Send above prompt to Claude Code

Step 3: Review the generated plan

The plan should include:

A short objective for the tool
Tasks grouped by file or feature
A proposed file structure
Suggested arguments, flags, and output behavior

Read the plan before approving it. This is where you catch missing behavior. If you forgot a flag or want different defaults, say it now. Changing the plan is cheaper than fixing code later

Step 4: Approve implementation and build the CLI

When the plan matches what you want, tell Claude: "Approve the plan, implement this." Claude should create the files, write the first version, set up package.json, and wire the executable

For dirscan, you'll get:

A src/cli.ts entry point that handles CLI execution
A src/scanner.ts module containing the core scanning logic
A src/wordlist.ts module for loading and normalizing wordlist entries
A src/results.ts module for human-readable and JSON output
A src/url.ts module for target validation and URL construction
A package.json with dependencies, scripts, and the bin field configured
Test files such as src/scanner.test.ts, src/wordlist.test.ts, and src/cli.test.ts

Claude writes working code, not placeholder stubs. The generated code handles:

Argument parsing with citty
Processing responses and categorizing status codes
Error handling for network issues, invalid URLs, and missing files

Step 5: Test the generated tool

After Claude finishes writing the code, test it to confirm everything works. Run the project checks first:

bun run typecheck
bun run lint
bun run test
bun run build

Then run the help command against the built executable:

node dist/cli.js --help

The help output should show the target URL argument, the wordlist argument, and flags such as --concurrency, --timeout, --status, --quiet, and --json. Then run a scan against a target you are authorized to test:

node dist/cli.js https://example.com ./wordlist.txt --json

For local development, create a small wordlist file with a few paths and run the CLI against a local test server or an application you control

Iterate with follow-up prompts

The first pass probably won't be perfect. Treat it like a scaffold and start tightening it. You can keep iterating in the same project to make it perfect

Useful follow-up prompts:

"Add a --concurrency flag to limit simultaneous requests to 10 by default"
"Add SOCKS proxy support so I can route scans through Tor"
"Add rate limiting to space requests 200ms apart so the scanner doesn't hammer the target"
"Fix the error handling for connection reset errors so the scan continues instead of aborting"
"Add CSV output format alongside JSON with an --output-csv flag"
"Add a --timeout flag that defaults to 5000ms for individual requests"

Claude can patch the existing files. You don't need to throw away the scaffold and start again. After a few passes, the tool should start matching the workflow you had in mind

For dirscan, expect two or three cleanup rounds before it feels usable outside a demo. The skill handles a lot of the mechanical edits. Your job is to decide how the tool should behave

What to watch out for

You still need enough JavaScript to read what Claude generated. Otherwise every bug becomes another prompt
You are still responsible for the tool. Scope, rate limits, and authorization are part of the build

Conclusion

npx-cli + Claude Code makes small security CLI projects easier to start. The boring setup work can shrink from a long afternoon to a short session. For a small tool, one focused session can get you something runnable

If you have a small security tool idea sitting in your notes, this workflow is a good way to get it running. The first version can come together faster than you expect

Ready to apply AI to your Security Engineering?

Subscribe to Secengai Newsletter for weekly actionable content on AI for security engineers.

This content reflects personal views, experiments, and use cases in AI and security engineering. It does not represent any employer's positions, policies, or practices.