Tabla de contenido
Una vez más aquí. Hoy vengo a dejar un pequeño programa que tenía a medio hacer es el disco de este equipo. El caso es que como tengo un dolor de mandíbula que no veo, pues me puse a añadirle cosas, y como ya no se me ocurre que más añadir, pues me decidí a subirlo … para tenerlo en algún sitio localizable, ya que el disco de este portátil se está muriendo. Bueno, el caso es que se trata de un pequeño programa de terminal para tomar apuntes sobre comandos de linux. El programa se llama Chuletario, que en su día giró a DiccioPynton (cuando le puse una interfaz gráfica y todas las mierdecillas que le puse en su día).
Si administras servidores o estudias administración de sistemas Linux, seguro que has acumulado notas sueltas por todas las esquinas de tu mesa: un grep aquí, un systemctl allá, un tar que solo usas dos veces al año. Chuletario reúne más de 420 comandos en 12 categorías (redes, logs, paquetes, Bash, usuarios, archivos…) y los presenta en una aplicación de terminal hecha con Python: tabla con colores, búsqueda, edición y hasta exportación a PDF. Comandos que se pueden ir ampliando a medida que nos va haciendo falta de forma muy sencilla y rápida.
En las siguientes líneas, vamos a ver qué es el proyecto, cómo funciona para el usuario y cómo está organizado el código por dentro — útil si quieres usarlo, contribuir o aprender de una arquitectura modular en Python.
¿Qué es Chuletario y para quién sirve?
Como decía, Chuletario es una chuleta interactiva de comandos Linux orientada a sysadmins, estudiantes de cursos de Linux y cualquier persona que quiera un recordatorio rápido en terminal sin abrir el navegador.
A diferencia de una página web estática o un PDF fijo, Chuletario permite:
- Consultar comandos por categoría (Procesos, Redes, Sistema, Bash…).
- Buscar por nombre, descripción, ejemplo o notas.
- Añadir, editar y eliminar entradas; los cambios se guardan en archivos JSON.
- Exportar toda la colección a Markdown o PDF.
- Usar una interfaz TUI (terminal gráfica) con filtro por categoría y panel de detalle.
- Ver advertencias en comandos delicados (
rm,dd, etc.), con notas personalizadas o detección automática.
No sustituye la documentación oficial (man), pero acelera el día a día y te deja construir tu chuleta personalizada. Nos va permitir guardar comandos que por el motivo que sea no quieres que salgan de tu equipo y acaben en los servidores de la IA de turno.
Cómo ejecutar Chuletario (sin complicaciones)
Solo necesitas Python 3.10+ instalado en tu equipo. El proyecto incluye un launcher, run_app.py, que va a:
- Crear el entorno virtual
.venvsi no existe. - Instalar dependencias desde
requirements.txt(rich,textual,reportlab). - Arrancar la aplicación con el Python del venv.
Para ello, en una terminal basta con utilizar lo siguientes comandos:
git clone https://github.com/entreunosyceros/chuletario.git cd chuletario python run_app.py
En Windows, usa py run_app.py o Windows Terminal; la chuleta funciona para consultar y editar, aunque muchos ejemplos Linux requieran WSL para ejecutarlos.
Menú principal (CLI)
Desde el menú, accedes a diferentes opciones con las teclas:
- buscar (B)
- añadir/editar/eliminar (A / D / X)
- exportar (M / P)
- recargar JSON (R)
- abrir TUI (T)
- ver una categoría (1-12)
- salir (0)
Interfaz TUI (Interfaz de Usuario de Texto)
Ideal para pantallas grandes. Incluye; filtro por categoría, búsqueda en vivo, tabla de comandos y panel lateral con descripción, ejemplo, advertencias y botones Ver ayuda (man) y Abrir docs.
Arquitectura del proyecto: datos y código separados
Una decisión clave para el mantenimiento: los comandos viven en modules/*.json y la lógica en el paquete app/.
chuletario/
├── main.py # Punto de entrada
├── run_app.py # Launcher (venv + pip + arranque)
├── requirements.txt # Dependencias Python
├── README.md
├── LICENSE # Licencia MIT
├── .gitignore
├── .venv/ # Entorno virtual (se crea al usar run_app.py; no en git)
├── img/
│ └── Chuletario.png # Imagen del repositorio
├── modules/ # Datos: un JSON por área (solo comandos)
│ ├── almacenamiento.json
│ ├── archivos.json
│ ├── backups.json
│ ├── bash.json
│ ├── logs.json
│ ├── paquetes.json
│ ├── permisos.json
│ ├── procesos.json
│ ├── redes.json
│ ├── servicios.json
│ ├── sistema.json
│ └── usuarios.json
└── app/ # Código Python
├── __init__.py
├── paths.py # Rutas del proyecto (multiplataforma)
├── platform.py # Ajustes de consola (UTF-8, ANSI en Windows)
├── constants.py # Constantes, créditos, reglas de peligro
├── console.py # Consola Rich y pausas
├── storage.py # Carga y guardado de modules/*.json
├── items.py # Campos opcionales y búsqueda en entradas
├── ayuda.py # man, documentación web, créditos
├── advertencias.py # Avisos explícitos e inferidos
├── catalog.py # Categorías, resolvers y ayudas CLI
├── crud.py # Crear, editar, eliminar, duplicados
├── cli/
│ ├── __init__.py
│ ├── menu.py # Menú principal
│ └── actions.py # Buscar, exportar, CRUD, créditos…
└── tui/
├── __init__.py
├── forms.py # Modales (añadir, editar, duplicados, créditos)
└── app.py # Aplicación Textual (tabla, filtros, detalle)
Así cualquiera puede ampliar la chuleta editando un JSON (por ejemplo bash.json para scripts de automatización) sin tocar Python, o mejorar la app sin mezclar datos con código. Aun que bueno, también se pueden aumentar los comandos guardados en los archivo json desde la propia aplicación … vamos que esto se puede ampliar de forma muy sencilla …
Las partes más importantes del código
1. app/storage.py — El corazón de los datos
Al iniciar, cargar_modulos() recorre modules/, lee cada .json y construye:
COMANDOS: diccionariocategoría → lista de entradas.ORIGEN: mapacategoría → ruta del archivopara saber dónde guardar al editar.
Cada entrada tiene la forma:
{
"comando": "ss",
"descripcion": "Sockets y conexiones",
"ejemplo": "ss -tulpn",
"notas": "Opcional",
"peligro": false,
"docs": "https://..."
}
guardar_categoria() persiste solo la categoría modificada en su JSON original. Eso evita reescribir todo el proyecto en cada inicio.
Las rutas usan app/paths.py (PROJECT_ROOT, MODULES_DIR), así el programa encuentra los JSON aunque ejecutes desde otra carpeta — importante en Windows.
2. app/catalog.py — Navegar la chuleta
Funciones como resolver_categoria() y resolver_comando() permiten elegir por número o nombre (insensible a mayúsculas). buscar_comando_global() detecta duplicados al crear comandos.
Esta capa desacopla la UI (CLI/TUI) del formato interno de los datos.
3. app/crud.py — Crear, editar y eliminar
crear_comando()/eliminar_item()/aplicar_edicion()modificanCOMANDOSy llaman aguardar_categoria().resolver_duplicado_al_añadir()gestiona conflictos: editar el existente, reemplazar o cancelar.
La lógica de negocio está centralizada; CLI y TUI solo llaman a estas funciones.
4. app/advertencias.py — Seguridad visual
Combina:
- Campos explícitos:
notas,peligro. - Heurística automática (binarios como
rm, patrones en ejemplos tiporm -rf).
La CLI muestra columna de advertencias; la TUI marca filas con ⚠ y detalla en el panel lateral. Misma regla en ambas interfaces gracias a texto_advertencias_item().
5. app/cli/ — Experiencia con Rich
menu.py: bucle del menú principal y tablas de categorías/acciones.actions.py: buscar, exportar MD/PDF, CRUD, créditos, mostrar categoría.
Rich aporta tablas, paneles y prompts legibles.
6. app/tui/ — Interfaz Textual
app.py: claseChuletarioTUI, tabla filtrable, selector de categoría, panel de detalle.forms.py: modales para añadir/editar con vista previa de advertencias.
La TUI usa cursor_type="row" en la tabla para actualizar el detalle al mover el cursor. Esto mejora la experiencia frente a un listado estático.
7. app/ayuda.py y app/platform.py — Multiplataforma
abrir_man():manen Linux/macOS; en Windows, WSL o documentación en navegador (man7.org).platform.py: UTF-8 y colores ANSI en consola Windows al arrancar.
8. run_app.py — Punto de entrada amigable
Orquesta venv, comprobación de dependencias (hash de requirements.txt) y mensajes informativos paso a paso. Es la puerta de entrada recomendada para usuarios que clonan el repo por primera vez.
9. main.py — Arranque mínimo
Solo configura el entorno y llama a menu(). Separación clara: launcher vs aplicación.
Tecnologías utilizadas (y por qué importan)
Categorías disponibles (contenido de la chuleta)
Entre otras: Procesos, Permisos, Servicios, Paquetes, Sistema, Almacenamiento, Backups, Logs, Redes, Usuarios y grupos, Archivos y carpetas y Bash (construcciones para scripts de automatización: set -euo pipefail, trap, getopts, arrays, etc.).
Puedes proponer nuevas categorías enviando un archivo JSON al repositorio o ampliando los tuyos en local.
Preguntas frecuentes (FAQ)
¿Chuletario ejecuta los comandos por mí?
Puede lanzar un comando en tu shell (E en CLI), pero su valor principal es consultar y gestionar la chuleta. En Windows, los ejemplos Linux suelen requerir WSL para ejecutarlos.
¿Necesito saber programar para usarlo?
No. Si sabes clonar un repo y ejecutar python run_app.py, puedes usarlo. Programar ayuda si quieres añadir categorías vía código.
¿Puedo usarlo sin conexión a internet?
Sí, salvo abrir documentación web o man online en Windows sin WSL.
¿Es código abierto?
Sí, licencia MIT. Puedes usarlo, modificarlo y redistribuirlo según la licencia.
Conclusión: una chuleta Linux que crece contigo
Chuletario no es solo una lista de comandos. La idea es tener una herramienta de terminal para organizar, buscar, personalizar y exportar tu conocimiento de Linux. Su código modular —JSON en modules/, lógica en app/— facilita el mantenimiento y las contribuciones.
Si a alguien le apetece probar esta pequeña aplicación, solo tiene que descargar el código fuente del repositorio en GitHub en el que he subido el proyecto y probarlo en su equipo.