DEV Community: Bora Kilicoglu

ferman: A Tiny CLI for Inspecting and Freeing Busy Ports

Bora Kilicoglu — Tue, 24 Mar 2026 16:40:46 +0000

Busy ports are one of those tiny problems that interrupt real work far more often than they should.

You start a dev server, a local database, a preview app, or a test runner, and something fails because a port is already in use. Then the usual dance begins:

check what is using the port
figure out whether it is safe to stop
kill the process
retry your actual work

That friction is exactly why I built ferman.

ferman is a small cross-platform CLI for inspecting busy ports, identifying the process behind them, and freeing them safely.

It is built for developers, but also for AI agents, scripts, and local automation workflows that need deterministic output and low ambiguity.

Why I built it

The core problem is simple:

a port is occupied
you need to know what is using it
you may want to free it

There are already OS-level commands for this, but they are not consistent across platforms, and they are not especially friendly for automation.

On macOS and Linux you might use lsof.
On Windows you might use netstat, tasklist, and taskkill.
If you are scripting around those commands, you also end up dealing with parsing, platform branching, and error handling.

I wanted one clean command that:

works across platforms
stays small
is readable for humans
is structured for machines

What ferman does

At the simplest level:

npx ferman 3000

It validates the port, checks whether it is busy, identifies the matching process when possible, and asks before termination.

There are a few core modes:

ferman 3000
ferman 3000 --force
ferman 3000 --dry
ferman 3000 --json
ferman 3000 --toon

It also supports more AI-oriented flows:

ferman 3000 5173 5432 --json
ferman --common --json
ferman --plan --json
ferman --doctor --json
ferman --json-schema
ferman 3000 --watch --json

Built for humans and agents

One thing I cared about from the start was making the tool work well in two very different contexts:

a developer using a terminal manually
a script, CI job, or AI agent using structured output

For humans, the CLI stays minimal and readable.

For machines, the output is deterministic and stable.

Example JSON output:

{
  "ok": true,
  "code": "PORT_RELEASED",
  "port": 3000,
  "busy": true,
  "processes": [
    {
      "pid": 1234,
      "name": "node"
    }
  ],
  "action": "killed",
  "message": "Port released."
}

Example error output:

{
  "ok": false,
  "code": "INVALID_PORT",
  "message": "Port must be a whole number."
}

That matters because once the output contract is stable, the CLI becomes much easier to compose into larger workflows.

AI-facing features

Over time, I pushed the project beyond the original “free a port” use case.

The current AI-facing surface includes:

strong JSON contract
stable machine error codes
TOON output for compact LLM-oriented structured data
multi-port support
--common for common local development ports
--plan for recommendation output
--doctor for local environment diagnosis
--json-schema for machine contract discovery
--watch for repeated snapshot events

This makes ferman more useful for:

local AI coding agents
shell automation
CI helpers
internal dev tooling
MCP-style wrappers and structured integrations

A few examples

Inspect without changing anything:

ferman 3000 --dry

Release immediately:

ferman 3000 --force

Check several ports at once:

ferman 3000 5173 5432 --json

Scan common dev ports:

ferman --common --json

Ask for the recommended next step:

ferman 3000 --plan --json

Get the output schema for integrations:

ferman --json-schema

Watch a port over time:

ferman 3000 --watch --json

Under the hood

The project is built in TypeScript and keeps dependencies intentionally small.

Platform-specific behavior is abstracted behind separate adapters:

macOS
Linux
Windows

The docs are built with VitePress, tests run with Vitest, and the package is published through GitHub Actions with trusted publishing.

I also added:

ESLint
Prettier
Husky
smoke checks
release checks

So even though the tool is small, the release workflow is treated seriously.

What I like about the result

I like that ferman stays narrow.

It does not try to be a general system monitor or a giant process manager.
It focuses on one annoying workflow and makes it much easier:

find what is using a port
understand whether action is needed
free the port when appropriate

That is enough to be useful every day.

Try it

If you want to try it:

npx ferman 3000

Project links:

GitHub: https://github.com/borakilicoglu/ferman
npm: https://www.npmjs.com/package/ferman
Docs: https://borakilicoglu.github.io/ferman/

If you build internal tooling, local automation, or AI-assisted developer workflows, I think this kind of CLI surface is worth investing in.

Small tools with predictable interfaces compound well.

sadrazam: A Dependency Hygiene CLI for JavaScript and TypeScript

Bora Kilicoglu — Tue, 24 Mar 2026 13:57:23 +0000

JavaScript and TypeScript projects get messy in a very predictable way.

A package gets added for a short experiment.
A build tool changes.
A migration leaves old dependencies behind.
A file stops being imported.
An export survives three refactors for no good reason.

A few months later, the project still works, but package.json and parts of the codebase no longer reflect reality.

That is why I built Sadrazam: a dependency and code-hygiene CLI for JavaScript and TypeScript projects.

Its goal is simple:

tell me what is actually used, what is not, and do it conservatively.

The problem with dependency cleanup tools

A lot of tooling in this space is useful, but the tradeoff is often the same: once a tool gets too aggressive, trust drops.

For me, dependency hygiene tooling needs a few things:

deterministic analysis over aggressive guessing
low false positives
clear CLI and reporter contracts
safe and narrow auto-fix behavior

I did not want a tool that “feels smart” but quietly makes risky edits.
I wanted a tool that behaves more like an engineer doing a careful review.

What Sadrazam does

Sadrazam analyzes a project by reading package.json, scanning source files, and comparing declared dependencies with actual usage.

It currently supports:

unused dependencies and devDependencies
missing package declarations
unused files
unused exports
package trace and export trace
script-aware dependency detection
workspace and monorepo scanning
CommonJS and hybrid import support
framework file scanning for .vue, .svelte, .astro, and .mdx
safe --fix and --fix --format
AI summaries via OpenAI, Anthropic, or Gemini

A quick example:


bash
npx sadrazam .
npx sadrazam . --trace typescript
npx sadrazam . --include unused-files,unused-exports
npx sadrazam . --fix --format

ajan-sql: Giving AI Safe, Read-Only SQL Access with MCP

Bora Kilicoglu — Mon, 23 Mar 2026 07:31:03 +0000

Safe SQL Access for AI with MCP

Giving an AI direct database access sounds useful immediately, and dangerous a few seconds later.

You want the model to inspect schema, understand relationships, run queries, and help with analysis. But you do not want it to mutate data, run unrestricted SQL, or pull back massive result sets because a prompt was vague.

That is the motivation behind ajan-sql.

ajan-sql is a small MCP server for SQL that gives AI clients schema-aware, read-only database access with a guard layer in front of query execution.

What `ajan-sql` does

ajan-sql runs as an MCP server over stdio and connects through DATABASE_URL.

It currently supports:

PostgreSQL
MySQL
SQLite

It exposes these tools:

server_info
list_tables
describe_table
list_relationships
search_schema
run_readonly_query
explain_query
sample_rows

It also exposes these schema resources:

schema://snapshot
schema://table/{name}

The goal is simple: give LLMs useful database visibility without handing them unsafe SQL execution.

Why I built it

A lot of AI plus database demos jump from "the model can write SQL" straight to "let it query production-like data."

That gap matters.

If you want something usable in practice, you need a few things:

schema discovery
safe defaults
hard query restrictions
predictable outputs for clients

I wanted something closer to:

psql plus schema awareness plus an AI-safe guard layer

But packaged in a way that works naturally with MCP clients.

The safety model

The core rule is that query execution must stay read-only and constrained.

ajan-sql enforces:

SELECT only, including guarded WITH ... SELECT queries
rejection of INSERT
rejection of UPDATE
rejection of DELETE
rejection of DROP
rejection of ALTER
rejection of TRUNCATE
rejection of multi-statement SQL
rejection of SQL comments
default LIMIT 100
max LIMIT 100
max query timeout of 5 seconds
max result size checks

That means the model can inspect and analyze, but it cannot mutate the database through this server.

Tooling that is actually useful

The schema tools are what make the server practical instead of just being a thin SQL wrapper.

`server_info`

Returns runtime details such as:

server version
active SQL dialect
available tools
available resources
readonly guard settings

`list_tables`

Returns visible tables and includes metadata such as:

schema
table name
table comment
estimated row count when available

`describe_table`

Returns:

columns
data types
nullability
default values
primary key metadata
unique metadata
foreign key references
index metadata

`list_relationships`

Returns foreign key relationships across the schema.

`search_schema`

Searches table names and column names with a simple substring match, which is useful when a client knows the concept but not the exact table.

`run_readonly_query`

Executes guarded SELECT queries and returns:

normalized SQL
row count
duration
column metadata
rows

`explain_query`

Runs a guarded explain plan and returns:

query timing
raw plan
a lightweight summary of the root plan node

`sample_rows`

Returns a limited sample from a table and can optionally target selected columns.

Structured outputs matter

One thing I wanted from the beginning was output that works well for both humans and clients.

So the tools return both:

content for a short human-readable summary
structuredContent for machine-friendly consumption

That makes the server easier to use from MCP-compatible clients that want stable structured payloads instead of parsing JSON out of plain text.

Example setup

Install it globally:

npm install -g ajan-sql

Run it with PostgreSQL:

DATABASE_DIALECT=postgres \
DATABASE_URL=postgres://USER:PASSWORD@HOST:PORT/DB ajan-sql

MySQL example:

DATABASE_DIALECT=mysql \
DATABASE_URL=mysql://USER:PASSWORD@HOST:PORT/DB ajan-sql

SQLite example:

DATABASE_DIALECT=sqlite \
DATABASE_URL=file:/absolute/path/to/database.sqlite ajan-sql

DATABASE_DIALECT defaults to postgres, so PostgreSQL users only need to set DATABASE_URL.

Adding `ajan-sql` to an MCP client

After installing ajan-sql, add it to your MCP client as a stdio server.

If your client can launch globally installed commands directly, use:

{
  "mcpServers": {
    "ajan-sql": {
      "command": "ajan-sql",
      "env": {
        "DATABASE_DIALECT": "postgres",
        "DATABASE_URL": "postgres://USER:PASSWORD@HOST:PORT/DB"
      }
    }
  }
}

If you are developing from the repository instead of a global install, point the client at the built CLI:

{
  "mcpServers": {
    "ajan-sql": {
      "command": "node",
      "args": ["/absolute/path/to/ajan-sql/dist/index.js"],
      "env": {
        "DATABASE_DIALECT": "postgres",
        "DATABASE_URL": "postgres://USER:PASSWORD@HOST:PORT/DB"
      }
    }
  }
}

For MySQL, set DATABASE_DIALECT to mysql and use a MySQL connection string.

For SQLite, set DATABASE_DIALECT to sqlite and use a file URL such as:

{
  "mcpServers": {
    "ajan-sql": {
      "command": "ajan-sql",
      "env": {
        "DATABASE_DIALECT": "sqlite",
        "DATABASE_URL": "file:/absolute/path/to/database.sqlite"
      }
    }
  }
}

Once the server is added, MCP clients can discover the available tools and resources automatically and start using schema inspection, relationship discovery, guarded query execution, explain plans, and sample rows through the standard MCP flow.

Why this shape works well for AI workflows

The point is not to let a model "do anything with SQL."

The point is to give it enough visibility to explore schema, understand relationships, inspect sample data, and answer analytical questions while keeping execution bounded and read-only.

That is the shape I wanted: useful enough for real AI workflows, constrained enough to trust in practice.

DEV Community: Bora Kilicoglu

ferman: A Tiny CLI for Inspecting and Freeing Busy Ports

Why I built it

What ferman does

Built for humans and agents

AI-facing features

A few examples

Under the hood

What I like about the result

Try it

sadrazam: A Dependency Hygiene CLI for JavaScript and TypeScript

The problem with dependency cleanup tools

What Sadrazam does

ajan-sql: Giving AI Safe, Read-Only SQL Access with MCP

Safe SQL Access for AI with MCP

What ajan-sql does

Why I built it

The safety model

Tooling that is actually useful

server_info

list_tables

describe_table

list_relationships

search_schema

run_readonly_query

explain_query

sample_rows

Structured outputs matter

Example setup

Adding ajan-sql to an MCP client

Why this shape works well for AI workflows

What `ajan-sql` does

`server_info`

`list_tables`

`describe_table`

`list_relationships`

`search_schema`

`run_readonly_query`

`explain_query`

`sample_rows`

Adding `ajan-sql` to an MCP client