How baibhab-adhikari/naturally-linux works
1. What this repo is
- naturally-linux is a Python CLI that converts a user’s natural-language prompt into a Linux shell command, then shows the command, explains it, applies safety checks, and only executes after confirmation.
- The architecture is centered around a linear “prompt → generated command → safety review → optional execution” flow.
2. Primary runtime boundary
- The main user entrypoint is the CLI, exposed through main.py, naturally_linux/__main__.py, and naturally_linux/cli.py.
- This is not a service or daemon; it is a local, interactive command-line application.
3. CLI orchestration layer
- naturally_linux/cli.py is the top-level coordinator.
- It likely parses subcommands and flags such as --dry-run, --timeout, and config ..., then routes work to the generator, safety, config, and executor subsystems.
- This layer owns the user interaction boundary: prompt input, command preview, explanation display, and confirmation before execution.
4. Command generation subsystem
- naturally_linux/generator.py is the AI-backed translation layer from natural language to shell command.
- The README indicates it uses a Groq API key, so this module is the external LLM boundary.
- The output of this subsystem is a proposed shell command plus explanatory text used by the CLI before any execution happens.
5. Safety subsystem
- naturally_linux/safety.py is the guardrail layer between generation and execution.
- Its job is to inspect the proposed command for unsafe patterns, risky operations, or other disallowed behavior before execution is permitted.
- This is a key architectural boundary: even if generation produces a command, safety can block it.
6. Execution subsystem
- naturally_linux/executor.py is responsible for actually running the command on the local system.
- It sits behind both the safety checks and the explicit user confirmation step.
- The README’s timeout option suggests execution is time-bounded, so this module likely handles process invocation and termination policy.
7. Configuration and secrets
- naturally_linux/config.py handles persistent CLI configuration, especially the Groq API key.
- The repo supports both environment-based configuration (GROQ_API_KEY) and CLI-managed storage via naturally-linux config set-key/show/delete.
- This module is the boundary between application logic and local user configuration/secrets management.
8. End-to-end data flow
- User types a request in the CLI.
- The CLI reads configuration, sends the request to the generator, receives a proposed command and explanation, runs safety validation, and presents the result.
- If not in dry-run mode and the user confirms, the executor runs the command locally; otherwise the flow stops after preview.
9. Dry-run and review-first behavior
- The architecture explicitly supports a non-executing preview path (--dry-run).
- This means command generation and explanation are reusable outputs independent of execution, which is important for safe review and for testing the generation path without side effects.
10. Testing boundaries
- tests/test_generator.py, tests/test_safety.py, and tests/test_executor.py map directly to the three main logic subsystems.
- That separation suggests each core module is designed with a narrow responsibility and can be tested independently from the CLI shell.
11. Packaging and runtime/tooling
- pyproject.toml and uv.lock show a packaged Python project intended for installation as a tool.
- The presence of .python-version suggests a pinned Python runtime, and the README recommends uv tool install naturally-linux, so distribution is built around standard Python packaging rather than a custom installer.
12. Docs and operational guidance
- docs/ and mkdocs.yml indicate the project has a documentation site with architecture, installation, safety, FAQ, and usage guidance.
- The docs likely mirror the code boundaries: how to install, how prompts flow through generation/safety/execution, and how safety constraints are intended to be used.
13. CI/release pipeline
- .github/workflows/ci.yml and .github/workflows/release.yml provide repository-level automation for validation and publishing.
- These pipelines are part of the engineering boundary around the CLI package, not the runtime behavior of the tool itself.
14. Architecture summary
- The key diagram should show one local CLI process orchestrating four internal modules: config, generator, safety, and executor.
- The only notable external dependency in the runtime path is the Groq API used for command generation; everything else is local to the user’s machine.
Main entry points: cli.py CLI · generator.py Generator · pyproject.toml Package · main.py main.py
Components 17
Runtime
Local command-line execution path
- main.py · Top-level launcher for the CLI
main.py - __main__ · Module entrypoint for `python -m` invocation
naturally_linux/__main__.py - CLI · Parses arguments and coordinates the user flow
naturally_linux/cli.py - Config · Loads and manages API key and local settings
naturally_linux/config.py - Generator · Converts natural language into a shell command and explanation
naturally_linux/generator.py - Groq API · Remote LLM boundary used for command generation
- Safety · Checks proposed commands for risky or disallowed behavior
naturally_linux/safety.py - Executor · Runs approved commands locally with timeout handling
naturally_linux/executor.py - User prompt · Natural-language request entered in the terminal
- Review · Displays command and explanation for user approval
Project
Repository packaging and supporting assets
- Package · Packaged CLI distribution and dependency metadata
pyproject.toml - Lockfile · Pinned dependency resolution for reproducible installs
uv.lock - Python version · Pinned interpreter version for local development
.python-version
Docs
User-facing documentation
- Docs · Project documentation site and usage guidance
docs/index.md - Architecture · Explains the system boundaries and command flow
docs/architecture.md
Connections 21
- main.py → CLI: launches · Starts the interactive application
- __main__ → CLI: invokes · Enables module-based entrypoint
- User prompt → CLI: enters · User request is passed into the CLI
- CLI → Config: reads · Loads API key and local settings
- Config → Generator: provides key · Supplies credentials for generation
- CLI → Generator: requests · Sends prompt for command generation
- Generator → Groq API: calls · Uses remote LLM service to infer command
- Groq API → Generator: returns · Provides proposed command and explanation
- Generator → Safety: hands off · Proposed command is reviewed before execution
- Safety → CLI: approves or blocks · Returns safety decision to the coordinator
- CLI → Review: shows · Presents command and explanation to the user
- Review → CLI: confirms · User approves or cancels execution
- CLI → Executor: executes · Runs the command only after safety and confirmation
- Executor → CLI: returns result · Reports output, status, or timeout outcome
- CLI → Review: dry-run · Preview-only path skips execution
- Package → main.py: packages · Defines the installable CLI entrypoint
- Lockfile → Package: pins deps · Supports reproducible installs
- Python version → Package: pins runtime · Records target Python version
- Docs → Architecture: links · Documentation site includes architecture guidance
- CI → Package: validates · Runs repository checks for the package
- Release → Package: publishes · Handles release automation for the package