nl2bash

Inspiration

A very common developer frustration inspired us: knowing what you want to do in the terminal, but forgetting the exact syntax, flags, or safest way to do it. Even experienced developers lose time context-switching to Google or Stack Overflow for commands they conceptually understand. Worse, running the wrong command can be destructive. We wanted a tool that translates intent directly into the correct command and makes safety explicit rather than implicit.

What it does

nl2bash converts natural language requests into executable bash commands. Given a plain-English description and an OS context, it returns copy-pasteable commands along with explanations, risk classifications, assumptions, and optional dry-run alternatives. The system blocks inherently dangerous operations and escalates risk for potentially destructive commands, helping users avoid costly mistakes while staying productive.

How we built it

We built nl2bash as a web application deployed on Vercel.

Frontend: React + TypeScript (Vite) for a fast, clean UI that displays commands, explanations, and safety metadata.
Backend/API: TypeScript API endpoint (/api/generate) that handles prompt construction, model calls, validation, and safety checks.
LLM Integration: The model is used as a proposal engine, not a trusted executor.
Safety Layer: Deterministic, rule-based validation that blocks dangerous commands, escalates risk levels, and enforces confirmation requirements.
Schema Validation: Zod schemas ensure every response matches a strict structure before it reaches the UI.

The architecture intentionally separates generation from safety so the system remains predictable and trustworthy.

Challenges we ran into

Framework and dependency conflicts: We had to reconcile different frontend setups and resolve lockfile conflicts cleanly to ensure reproducible builds.
Local testing confusion: Running frontend and backend in different dev environments caused early 404 and routing issues, which we solved by clearly separating concerns and validating endpoints with curl.
Safety design: Relying on prompting alone was not enough. We had to implement explicit blocking and escalation logic to prevent unsafe outputs.
Windows compatibility: Tooling differences (like missing Unix commands) required extra care during setup and cleanup.

Accomplishments that we're proud of

Building a safety-first command generation system instead of a raw “AI autocomplete.”
Successfully blocking dangerous operations while still producing useful alternatives.
Returning structured, explainable outputs rather than opaque text responses.
Designing an API that is both user-friendly and programmatically reliable.

What we learned

Safety must be enforced after generation, not just suggested in prompts.
Strict schemas dramatically improve reliability and frontend simplicity.
Developers value clarity and confidence more than verbosity.
Small tooling details (lockfiles, ports, OS differences) matter a lot in real projects.