Skip to content

PROJECT_JOURNEY.md

Latest commit

 

History

History
58 lines (35 loc) · 5.59 KB

PROJECT_JOURNEY.md

File metadata and controls

58 lines (35 loc) · 5.59 KB
Raw

Project Journey: QuickRef

1. Why I Built This

I built QuickRef because I was constantly breaking my flow state. While learning Linux, networking, Git, and cybersecurity, I found myself repeatedly forgetting the exact syntax or specific options for terminal commands.

Opening a browser to Google chmod or tar syntax meant leaving the terminal, getting distracted, and wasting time. While man pages exist, they are often too dense for a quick refresher, and tools like tldr are great but aren't tailored to my specific learning path. I wanted a fast, completely offline, personal knowledge base that I could query instantly without leaving the command line. I built it myself so I could control exactly how the information was structured and formatted for my brain.

2. The Problem

For developers and cybersecurity students, the terminal is the primary workspace. Context switching is expensive. Every time you have to open a browser to look up a command, you lose focus.

If this problem is ignored, you end up relying heavily on copy-pasting from StackOverflow rather than actually committing commands to memory. QuickRef addresses this by bringing a highly structured, readable, and curated reference sheet directly into the terminal, optimizing for speed and learning ("FAST → CLEAR → PRACTICAL → LEARN").

3. My Approach

I built QuickRef entirely in Python using standard libraries (argparse, json) to keep the footprint as light as possible and ensure it runs flawlessly on any system (macOS, Linux, Ubuntu, Kali).

Instead of a complex database like SQLite, I used a structured commands.json file. This choice was deliberate: it makes adding new commands trivial (just editing a JSON file), keeps the data portable, and allows it to be version-controlled in Git effortlessly.

For the presentation layer, I strictly avoided bulky third-party UI libraries (like rich) and wrote a custom formatter using raw ANSI escape codes. This ensured the CLI remained lightning-fast while still providing a beautiful, hierarchical visual experience (bold titles, cyan commands, dimmed categories).

4. Challenges I Faced

Structuring for Readability

The Difficulty: Dumping JSON text to a terminal is easy, but making it highly scannable and readable for daily use is hard. Initially, the output felt like a wall of data. The Solution: I had to completely redesign the presentation layer. I created a formatter.py module with a custom Style class that applies ANSI formatting based on terminal support (sys.stdout.isatty()). I manually tuned the vertical whitespace, ensuring exactly one blank line separated major sections and individual examples, which drastically improved cognitive parsing.

Global Installation & Pathing

The Difficulty: I wanted to type quickref anywhere in my OS, not just python3 cli.py inside the project folder. The Solution: I had to learn how to properly package a Python application using setup.py and entry_points. A major challenge arose when trying to load the commands.json file globally; I had to use __file__ inside data.py to dynamically resolve the absolute path to the data file relative to the installed package directory, rather than relying on the user's current working directory.

5. What I Learned

Technical

  • Python Packaging: I learned how to use setuptools, configure console_scripts, and include package_data so a Python script can be installed natively as a system-wide CLI tool via pip install -e ..
  • Terminal APIs: I learned how to detect if a script is running interactively in a terminal using sys.stdout.isatty(), allowing me to strip ANSI color codes if the output is being piped to another file or command.

Problem Solving

  • Search & Filtering: I implemented a custom search function that iterates through the JSON dataset, matching keywords and descriptions, proving how powerful simple text parsing can be before reaching for heavy search indexing tools.

Engineering

  • Modularity: I learned the value of separating concerns. By splitting the code into cli.py (routing), core.py (logic), data.py (file I/O), and formatter.py (UI), the codebase became significantly easier to debug and extend.

6. What I Would Improve

If I continue expanding QuickRef, I would prioritize:

  1. Interactive Quizzes (--quiz): A feature to hide the syntax and prompt the user with a scenario (e.g., "Make this file executable"), forcing them to type the correct command to build muscle memory.
  2. Usage Statistics: Tracking which commands are searched for the most locally, helping me identify exactly where my knowledge gaps are.
  3. Personal Notes: Allowing the CLI to append custom notes or "gotchas" to a command directly from the terminal without having to manually open the JSON file.

7. What This Project Taught Me About the Real World

This project taught me that User Experience (UX) is not just for graphical web applications. In the real world, developers and sysadmins spend hours in the terminal, and poorly formatted, dense text output is a major friction point. Taking the time to properly format, color-code, and space terminal output transforms a script from a raw utility into an actual product.

8. Final Takeaway

QuickRef was absolutely worth building because it solved an immediate, personal pain point while forcing me to learn proper Python application packaging. The most important thing I learned is how to architect a terminal application for global use across an operating system. This project has prepared me to build much more complex, system-level CLI utilities and automation scripts in the future.